calvyn-code 0.14.0

package/optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

@@ -0,0 +1,3136 @@
+#!/usr/bin/env python3
+"""OpenClaw -> Hermes migration helper.
+
+This script migrates the parts of an OpenClaw user footprint that map cleanly
+into Hermes Agent, archives selected unmapped docs for manual review, and
+reports exactly what was skipped and why.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+try:
+    import yaml
+except Exception:  # pragma: no cover - handled at runtime
+    yaml = None
+
+
+ENTRY_DELIMITER = "\n§\n"
+DEFAULT_MEMORY_CHAR_LIMIT = 2200
+DEFAULT_USER_CHAR_LIMIT = 1375
+SKILL_CATEGORY_DIRNAME = "openclaw-imports"
+SKILL_CATEGORY_DESCRIPTION = (
+    "Skills migrated from an OpenClaw workspace."
+)
+SKILL_CONFLICT_MODES = {"skip", "overwrite", "rename"}
+SUPPORTED_SECRET_TARGETS={
+    "TELEGRAM_BOT_TOKEN",
+    "OPENROUTER_API_KEY",
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "ELEVENLABS_API_KEY",
+    "VOICE_TOOLS_OPENAI_KEY",
+}
+WORKSPACE_INSTRUCTIONS_FILENAME = "AGENTS" + ".md"
+MIGRATION_OPTION_METADATA: Dict[str, Dict[str, str]] = {
+    "soul": {
+        "label": "SOUL.md",
+        "description": "Import the OpenClaw persona file into Hermes.",
+    },
+    "workspace-agents": {
+        "label": "Workspace instructions",
+        "description": "Copy the OpenClaw workspace instructions file into a chosen workspace.",
+    },
+    "memory": {
+        "label": "MEMORY.md",
+        "description": "Import long-term memory entries into Hermes memories.",
+    },
+    "user-profile": {
+        "label": "USER.md",
+        "description": "Import user profile entries into Hermes memories.",
+    },
+    "messaging-settings": {
+        "label": "Messaging settings",
+        "description": "Import Hermes-compatible messaging settings such as allowlists and working directory.",
+    },
+    "secret-settings": {
+        "label": "Allowlisted secrets",
+        "description": "Import the small allowlist of Hermes-compatible secrets when explicitly enabled.",
+    },
+    "command-allowlist": {
+        "label": "Command allowlist",
+        "description": "Merge OpenClaw exec approval patterns into Hermes command_allowlist.",
+    },
+    "skills": {
+        "label": "User skills",
+        "description": "Copy OpenClaw skills into ~/.hermes/skills/openclaw-imports/.",
+    },
+    "tts-assets": {
+        "label": "TTS assets",
+        "description": "Copy compatible workspace TTS assets into ~/.hermes/tts/.",
+    },
+    "discord-settings": {
+        "label": "Discord settings",
+        "description": "Import Discord bot token and allowlist into Hermes .env.",
+    },
+    "slack-settings": {
+        "label": "Slack settings",
+        "description": "Import Slack bot/app tokens and allowlist into Hermes .env.",
+    },
+    "whatsapp-settings": {
+        "label": "WhatsApp settings",
+        "description": "Import WhatsApp allowlist into Hermes .env.",
+    },
+    "signal-settings": {
+        "label": "Signal settings",
+        "description": "Import Signal account, HTTP URL, and allowlist into Hermes .env.",
+    },
+    "provider-keys": {
+        "label": "Provider API keys",
+        "description": "Import model provider API keys into Hermes .env (requires --migrate-secrets).",
+    },
+    "model-config": {
+        "label": "Default model",
+        "description": "Import the default model setting into Hermes config.yaml.",
+    },
+    "tts-config": {
+        "label": "TTS configuration",
+        "description": "Import TTS provider and voice settings into Hermes config.yaml.",
+    },
+    "shared-skills": {
+        "label": "Shared skills",
+        "description": "Copy shared OpenClaw skills from ~/.openclaw/skills/ into Hermes.",
+    },
+    "daily-memory": {
+        "label": "Daily memory files",
+        "description": "Merge daily memory entries from workspace/memory/ into Hermes MEMORY.md.",
+    },
+    "archive": {
+        "label": "Archive unmapped docs",
+        "description": "Archive compatible-but-unmapped docs for later manual review.",
+    },
+    "mcp-servers": {
+        "label": "MCP servers",
+        "description": "Import MCP server definitions from OpenClaw into Hermes config.yaml.",
+    },
+    "plugins-config": {
+        "label": "Plugins configuration",
+        "description": "Archive OpenClaw plugin configuration and installed extensions for manual review.",
+    },
+    "cron-jobs": {
+        "label": "Cron / scheduled tasks",
+        "description": "Import cron job definitions. Archive for manual recreation via 'hermes cron'.",
+    },
+    "hooks-config": {
+        "label": "Hooks and webhooks",
+        "description": "Archive OpenClaw hook configuration (internal hooks, webhooks, Gmail integration).",
+    },
+    "agent-config": {
+        "label": "Agent defaults and multi-agent setup",
+        "description": "Import agent defaults (compaction, context, thinking) into Hermes config. Archive multi-agent list.",
+    },
+    "gateway-config": {
+        "label": "Gateway configuration",
+        "description": "Import gateway port and auth settings. Archive full gateway config for manual setup.",
+    },
+    "session-config": {
+        "label": "Session configuration",
+        "description": "Import session reset policies (daily/idle) into Hermes session_reset config.",
+    },
+    "full-providers": {
+        "label": "Full model provider definitions",
+        "description": "Import custom model providers (baseUrl, apiType, headers) into Hermes custom_providers.",
+    },
+    "deep-channels": {
+        "label": "Deep channel configuration",
+        "description": "Import extended channel settings (Matrix, Mattermost, IRC, group configs). Archive complex settings.",
+    },
+    "browser-config": {
+        "label": "Browser configuration",
+        "description": "Import browser automation settings into Hermes config.yaml.",
+    },
+    "tools-config": {
+        "label": "Tools configuration",
+        "description": "Import tool settings (exec timeout, sandbox, web search) into Hermes config.yaml.",
+    },
+    "approvals-config": {
+        "label": "Approval rules",
+        "description": "Import approval mode and rules into Hermes config.yaml approvals section.",
+    },
+    "memory-backend": {
+        "label": "Memory backend configuration",
+        "description": "Archive OpenClaw memory backend settings (QMD, vector search, citations) for manual review.",
+    },
+    "skills-config": {
+        "label": "Skills registry configuration",
+        "description": "Archive per-skill enabled/config/env settings from OpenClaw skills.entries.",
+    },
+    "ui-identity": {
+        "label": "UI and identity settings",
+        "description": "Archive OpenClaw UI theme, assistant identity, and display preferences.",
+    },
+    "logging-config": {
+        "label": "Logging and diagnostics",
+        "description": "Archive OpenClaw logging and diagnostics configuration.",
+    },
+}
+MIGRATION_PRESETS: Dict[str, set[str]] = {
+    "user-data": {
+        "soul",
+        "workspace-agents",
+        "memory",
+        "user-profile",
+        "messaging-settings",
+        "command-allowlist",
+        "skills",
+        "tts-assets",
+        "discord-settings",
+        "slack-settings",
+        "whatsapp-settings",
+        "signal-settings",
+        "model-config",
+        "tts-config",
+        "shared-skills",
+        "daily-memory",
+        "archive",
+        "mcp-servers",
+        "agent-config",
+        "session-config",
+        "browser-config",
+        "tools-config",
+        "approvals-config",
+        "deep-channels",
+        "full-providers",
+        "plugins-config",
+        "cron-jobs",
+        "hooks-config",
+        "memory-backend",
+        "skills-config",
+        "ui-identity",
+        "logging-config",
+        "gateway-config",
+    },
+    "full": set(MIGRATION_OPTION_METADATA),
+}
+
+
+# ───────────────────────────────────────────────────────────────────────
+# Item shape constants — kept stable for downstream consumers of report.json.
+# Inspired by OpenClaw's src/plugin-sdk/migration.ts so both sides speak the
+# same vocabulary.  Values intentionally match the strings already produced
+# by this script (migrated/archived/skipped/conflict/error) so the addition
+# is backward-compatible.
+# ───────────────────────────────────────────────────────────────────────
+STATUS_MIGRATED = "migrated"
+STATUS_ARCHIVED = "archived"
+STATUS_SKIPPED = "skipped"
+STATUS_CONFLICT = "conflict"
+STATUS_ERROR = "error"
+STATUS_PLANNED = "planned"
+
+REASON_TARGET_EXISTS = "Target exists and overwrite is disabled"
+REASON_BLOCKED_BY_APPLY_CONFLICT = "blocked by earlier apply conflict"
+
+
+@dataclass
+class ItemResult:
+    kind: str
+    source: Optional[str]
+    destination: Optional[str]
+    status: str
+    reason: str = ""
+    details: Dict[str, Any] = field(default_factory=dict)
+    sensitive: bool = False
+
+
+def parse_selection_values(values: Optional[Sequence[str]]) -> List[str]:
+    parsed: List[str] = []
+    for value in values or ():
+        for part in str(value).split(","):
+            part = part.strip().lower()
+            if part:
+                parsed.append(part)
+    return parsed
+
+
+def resolve_selected_options(
+    include: Optional[Sequence[str]] = None,
+    exclude: Optional[Sequence[str]] = None,
+    preset: Optional[str] = None,
+) -> set[str]:
+    include_values = parse_selection_values(include)
+    exclude_values = parse_selection_values(exclude)
+    valid = set(MIGRATION_OPTION_METADATA)
+    preset_name = (preset or "").strip().lower()
+
+    if preset_name and preset_name not in MIGRATION_PRESETS:
+        raise ValueError(
+            "Unknown migration preset: "
+            + preset_name
+            + ". Valid presets: "
+            + ", ".join(sorted(MIGRATION_PRESETS))
+        )
+
+    unknown = (set(include_values) - {"all"} - valid) | (set(exclude_values) - {"all"} - valid)
+    if unknown:
+        raise ValueError(
+            "Unknown migration option(s): "
+            + ", ".join(sorted(unknown))
+            + ". Valid options: "
+            + ", ".join(sorted(valid))
+        )
+
+    if preset_name:
+        selected = set(MIGRATION_PRESETS[preset_name])
+    elif not include_values or "all" in include_values:
+        selected = set(valid)
+    else:
+        selected = set(include_values)
+
+    if "all" in exclude_values:
+        selected.clear()
+    selected -= (set(exclude_values) - {"all"})
+    return selected
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def normalize_text(text: str) -> str:
+    return re.sub(r"\s+", " ", text.strip())
+
+
+def ensure_parent(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def resolve_secret_input(value: Any, env: Optional[Dict[str, str]] = None) -> Optional[str]:
+    """Resolve an OpenClaw SecretInput value to a plain string.
+
+    SecretInput can be:
+    - A plain string: "sk-..."
+    - An env template: "${OPENROUTER_API_KEY}"
+    - A SecretRef object: {"source": "env", "id": "OPENROUTER_API_KEY"}
+    """
+    if isinstance(value, str):
+        # Check for env template: "${VAR_NAME}"
+        m = re.match(r"^\$\{(\w+)\}$", value.strip())
+        if m and env:
+            return env.get(m.group(1), "").strip() or None
+        return value.strip() or None
+    if isinstance(value, dict):
+        source = value.get("source", "")
+        ref_id = value.get("id", "")
+        if source == "env" and ref_id and env:
+            return env.get(ref_id, "").strip() or None
+        # File/exec sources can't be resolved here — return None
+    return None
+
+
+def load_yaml_file(path: Path) -> Dict[str, Any]:
+    if yaml is None or not path.exists():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+def dump_yaml_file(path: Path, data: Dict[str, Any]) -> None:
+    if yaml is None:
+        raise RuntimeError("PyYAML is required to update Hermes config.yaml")
+    ensure_parent(path)
+    path.write_text(
+        yaml.safe_dump(data, sort_keys=False, allow_unicode=False),
+        encoding="utf-8",
+    )
+
+
+def parse_env_file(path: Path) -> Dict[str, str]:
+    if not path.exists():
+        return {}
+    data: Dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        data[key.strip()] = value.strip()
+    return data
+
+
+def save_env_file(path: Path, data: Dict[str, str]) -> None:
+    ensure_parent(path)
+    lines = [f"{key}={value}" for key, value in data.items()]
+    path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+def backup_existing(path: Path, backup_root: Path) -> Optional[Path]:
+    if not path.exists():
+        return None
+    rel = Path(*path.parts[1:]) if path.is_absolute() and len(path.parts) > 1 else path
+    dest = backup_root / rel
+    ensure_parent(dest)
+    if path.is_dir():
+        shutil.copytree(path, dest, dirs_exist_ok=True)
+    else:
+        shutil.copy2(path, dest)
+    return dest
+
+
+# ── Brand rewriting ─────────────────────────────────────────
+# Replace OpenClaw brand names with Hermes in migrated text so that
+# memory entries, user profiles, SOUL.md, and workspace instructions
+# read as self-referential to the new agent identity.
+#
+# Case-preserving: ``OpenClaw`` → ``Hermes`` (prose), but lowercase matches
+# like ``openclaw`` → ``hermes`` (so filesystem paths like ``~/.openclaw``
+# become ``~/.hermes`` — the real Hermes home — not the broken ``~/.Hermes``).
+_REBRAND_PATTERNS: List[Tuple[re.Pattern, str]] = [
+    (re.compile(r'\bOpen[\s-]?Claw\b', re.IGNORECASE), 'Hermes'),
+    (re.compile(r'\bClawdBot\b', re.IGNORECASE), 'Hermes'),
+    (re.compile(r'\bMoltBot\b', re.IGNORECASE), 'Hermes'),
+]
+
+
+def _case_preserving_replacement(replacement: str):
+    """Return a re.sub replacement fn that lowercases the result when the
+    matched text was all-lowercase.
+
+    Keeps ``OpenClaw`` → ``Hermes`` but maps ``openclaw`` → ``hermes`` so a
+    filesystem path like ``~/.openclaw/config.yaml`` rewrites to
+    ``~/.hermes/config.yaml`` (the real Hermes home) instead of the broken
+    ``~/.Hermes/config.yaml``.
+    """
+    def _sub(match: "re.Match[str]") -> str:
+        matched = match.group(0)
+        if matched and matched.islower():
+            return replacement.lower()
+        return replacement
+    return _sub
+
+
+def rebrand_text(text: str) -> str:
+    """Replace OpenClaw / ClawdBot / MoltBot brand names with Hermes.
+
+    Preserves case so filesystem-path matches (lowercase) don't become
+    capitalized directory names that don't exist.
+    """
+    for pattern, replacement in _REBRAND_PATTERNS:
+        text = pattern.sub(_case_preserving_replacement(replacement), text)
+    return text
+
+
+def parse_existing_memory_entries(path: Path) -> List[str]:
+    if not path.exists():
+        return []
+    raw = read_text(path)
+    if not raw.strip():
+        return []
+    if ENTRY_DELIMITER in raw:
+        return [e.strip() for e in raw.split(ENTRY_DELIMITER) if e.strip()]
+    return extract_markdown_entries(raw)
+
+
+def extract_markdown_entries(text: str) -> List[str]:
+    entries: List[str] = []
+    headings: List[str] = []
+    paragraph_lines: List[str] = []
+
+    def context_prefix() -> str:
+        filtered = [h for h in headings if h and not re.search(r"\b(MEMORY|USER|SOUL|AGENTS|TOOLS|IDENTITY)\.md\b", h, re.I)]
+        return " > ".join(filtered)
+
+    def flush_paragraph() -> None:
+        nonlocal paragraph_lines
+        if not paragraph_lines:
+            return
+        text_block = " ".join(line.strip() for line in paragraph_lines).strip()
+        paragraph_lines = []
+        if not text_block:
+            return
+        prefix = context_prefix()
+        if prefix:
+            entries.append(f"{prefix}: {text_block}")
+        else:
+            entries.append(text_block)
+
+    in_code_block = False
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            flush_paragraph()
+            continue
+        if in_code_block:
+            continue
+
+        heading_match = re.match(r"^(#{1,6})\s+(.*\S)\s*$", stripped)
+        if heading_match:
+            flush_paragraph()
+            level = len(heading_match.group(1))
+            text_value = heading_match.group(2).strip()
+            while len(headings) >= level:
+                headings.pop()
+            headings.append(text_value)
+            continue
+
+        bullet_match = re.match(r"^\s*(?:[-*]|\d+\.)\s+(.*\S)\s*$", line)
+        if bullet_match:
+            flush_paragraph()
+            content = bullet_match.group(1).strip()
+            prefix = context_prefix()
+            entries.append(f"{prefix}: {content}" if prefix else content)
+            continue
+
+        if not stripped:
+            flush_paragraph()
+            continue
+
+        if stripped.startswith("|") and stripped.endswith("|"):
+            flush_paragraph()
+            continue
+
+        paragraph_lines.append(stripped)
+
+    flush_paragraph()
+
+    deduped: List[str] = []
+    seen = set()
+    for entry in entries:
+        normalized = normalize_text(entry)
+        if not normalized or normalized in seen:
+            continue
+        seen.add(normalized)
+        deduped.append(entry.strip())
+    return deduped
+
+
+def merge_entries(
+    existing: Sequence[str],
+    incoming: Sequence[str],
+    limit: int,
+) -> Tuple[List[str], Dict[str, int], List[str]]:
+    merged = list(existing)
+    seen = {normalize_text(entry) for entry in existing if entry.strip()}
+    stats = {"existing": len(existing), "added": 0, "duplicates": 0, "overflowed": 0}
+    overflowed: List[str] = []
+
+    current_len = len(ENTRY_DELIMITER.join(merged)) if merged else 0
+
+    for entry in incoming:
+        normalized = normalize_text(entry)
+        if not normalized:
+            continue
+        if normalized in seen:
+            stats["duplicates"] += 1
+            continue
+
+        candidate_len = len(entry) if not merged else current_len + len(ENTRY_DELIMITER) + len(entry)
+        if candidate_len > limit:
+            stats["overflowed"] += 1
+            overflowed.append(entry)
+            continue
+
+        merged.append(entry)
+        seen.add(normalized)
+        current_len = candidate_len
+        stats["added"] += 1
+
+    return merged, stats, overflowed
+
+
+def relative_label(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+# ───────────────────────────────────────────────────────────────────────
+# Secret redaction for migration reports.
+#
+# The report JSON persists to disk inside the migration output directory and
+# frequently ends up in bug reports or support channels.  Anything that looks
+# like a credential — by key name or by value shape — is replaced with
+# "[redacted]" before the report is written.
+#
+# Modelled on OpenClaw's src/plugin-sdk/migration.ts so both migration tools
+# redact consistently.  Pure function — safe to call on any plain-data dict.
+# ───────────────────────────────────────────────────────────────────────
+REDACTED_MIGRATION_VALUE = "[redacted]"
+
+_SECRET_KEY_MARKERS = (
+    "accesstoken",
+    "apikey",
+    "authorization",
+    "bearertoken",
+    "clientsecret",
+    "cookie",
+    "credential",
+    "password",
+    "privatekey",
+    "refreshtoken",
+    "secret",
+)
+
+_SECRET_VALUE_PATTERNS = (
+    re.compile(r"\bBearer\s+[A-Za-z0-9._~+/=\-]+"),
+    re.compile(r"\bsk-[A-Za-z0-9_\-]{8,}\b"),
+    re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{16,}\b"),
+    re.compile(r"\bxox[abprs]-[A-Za-z0-9\-]{8,}\b"),
+    re.compile(r"\bAIza[0-9A-Za-z_\-]{12,}\b"),
+)
+
+
+def _normalize_secret_key(key: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", key.lower())
+
+
+def _is_secret_key(key: str) -> bool:
+    normalized = _normalize_secret_key(key)
+    if normalized == "token" or normalized.endswith("token"):
+        return True
+    if normalized in ("auth", "authorization"):
+        return True
+    return any(marker in normalized for marker in _SECRET_KEY_MARKERS)
+
+
+def _redact_string(value: str) -> str:
+    for pattern in _SECRET_VALUE_PATTERNS:
+        value = pattern.sub(REDACTED_MIGRATION_VALUE, value)
+    return value
+
+
+def redact_migration_value(value: Any) -> Any:
+    """Return a deep copy of ``value`` with secret-looking content replaced.
+
+    Applied to every report written to disk.  Keys whose normalized form
+    matches a credential marker get their value replaced wholesale.  Strings
+    anywhere in the tree are scanned for common token patterns (sk-..., ghp_...,
+    xox*-, AIza*, Bearer ...) and those substrings are replaced inline.
+    """
+    return _redact_internal(value, set())
+
+
+def _redact_internal(value: Any, seen: set) -> Any:
+    if isinstance(value, str):
+        return _redact_string(value)
+    if isinstance(value, (list, tuple)):
+        return [_redact_internal(entry, seen) for entry in value]
+    if isinstance(value, dict):
+        obj_id = id(value)
+        if obj_id in seen:
+            return REDACTED_MIGRATION_VALUE
+        seen.add(obj_id)
+        out: Dict[str, Any] = {}
+        for key, entry in value.items():
+            if isinstance(key, str) and _is_secret_key(key):
+                out[key] = REDACTED_MIGRATION_VALUE
+            else:
+                out[key] = _redact_internal(entry, seen)
+        return out
+    return value
+
+
+def write_report(output_dir: Path, report: Dict[str, Any]) -> None:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    # Always redact before persisting.  Callers who need the raw object
+    # (in-process) still get it back from build_report(); only the on-disk
+    # copy is redacted.
+    redacted = redact_migration_value(report)
+    (output_dir / "report.json").write_text(
+        json.dumps(redacted, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+    grouped: Dict[str, List[Dict[str, Any]]] = {}
+    for item in redacted["items"]:
+        grouped.setdefault(item["status"], []).append(item)
+
+    lines = [
+        "# OpenClaw -> Hermes Migration Report",
+        "",
+        f"- Timestamp: {redacted['timestamp']}",
+        f"- Mode: {redacted['mode']}",
+        f"- Source: `{redacted['source_root']}`",
+        f"- Target: `{redacted['target_root']}`",
+        "",
+        "## Summary",
+        "",
+    ]
+
+    for key, value in redacted["summary"].items():
+        lines.append(f"- {key}: {value}")
+
+    warnings = redacted.get("warnings") or []
+    if warnings:
+        lines.extend(["", "## Warnings", ""])
+        for warning in warnings:
+            lines.append(f"- {warning}")
+
+    lines.extend(["", "## What Was Not Fully Brought Over", ""])
+    skipped = grouped.get("skipped", []) + grouped.get("conflict", []) + grouped.get("error", [])
+    if not skipped:
+        lines.append("- Nothing. All discovered items were either migrated or archived.")
+    else:
+        for item in skipped:
+            source = item["source"] or "(n/a)"
+            dest = item["destination"] or "(n/a)"
+            reason = item["reason"] or item["status"]
+            lines.append(f"- `{source}` -> `{dest}`: {reason}")
+
+    next_steps = redacted.get("next_steps") or []
+    if next_steps:
+        lines.extend(["", "## Next Steps", ""])
+        for step in next_steps:
+            lines.append(f"- {step}")
+
+    (output_dir / "summary.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+class Migrator:
+    def __init__(
+        self,
+        source_root: Path,
+        target_root: Path,
+        execute: bool,
+        workspace_target: Optional[Path],
+        overwrite: bool,
+        migrate_secrets: bool,
+        output_dir: Optional[Path],
+        selected_options: Optional[set[str]] = None,
+        preset_name: str = "",
+        skill_conflict_mode: str = "skip",
+    ):
+        self.source_root = source_root
+        self.target_root = target_root
+        self.execute = execute
+        self.workspace_target = workspace_target
+        self.overwrite = overwrite
+        self.migrate_secrets = migrate_secrets
+        self.selected_options = set(selected_options or MIGRATION_OPTION_METADATA.keys())
+        self.preset_name = preset_name.strip().lower()
+        self.skill_conflict_mode = skill_conflict_mode.strip().lower() or "skip"
+        self.timestamp = datetime.now().strftime("%Y%m%dT%H%M%S")
+        self.output_dir = output_dir or (
+            target_root / "migration" / "openclaw" / self.timestamp if execute else None
+        )
+        self.archive_dir = self.output_dir / "archive" if self.output_dir else None
+        self.backup_dir = self.output_dir / "backups" if self.output_dir else None
+        self.overflow_dir = self.output_dir / "overflow" if self.output_dir else None
+        self.items: List[ItemResult] = []
+        # Once a config.yaml write hits conflict/error mid-run, later
+        # config.yaml writes are deliberately short-circuited to avoid
+        # leaving config in a partially-written state.  Modelled on
+        # OpenClaw's extensions/migrate-hermes/apply.ts "blocked by earlier
+        # apply conflict" sequencing.
+        self._config_apply_blocked: bool = False
+
+        # Resolve the configured workspace directory from openclaw.json.
+        # Many users (especially those who started before the OpenClaw rebrand)
+        # have a custom workspace path (e.g. ~/clawd/) that differs from the
+        # default ~/.openclaw/workspace/.  Reading agents.defaults.workspace
+        # lets source_candidate() find files in the actual workspace.
+        self._custom_workspace: Optional[Path] = None
+        oc_config = self.load_openclaw_config()
+        ws = (oc_config.get("agents", {}).get("defaults", {}).get("workspace") or "").strip()
+        if ws:
+            ws_path = Path(ws).expanduser().resolve()
+            # Only use it if it exists and is outside the source_root tree
+            # (otherwise the standard relative-path logic already covers it).
+            if ws_path.is_dir():
+                try:
+                    ws_path.relative_to(self.source_root)
+                except ValueError:
+                    # ws_path is outside source_root — use it as custom workspace
+                    self._custom_workspace = ws_path
+
+        config = load_yaml_file(self.target_root / "config.yaml")
+        mem_cfg = config.get("memory", {}) if isinstance(config.get("memory"), dict) else {}
+        self.memory_limit = int(mem_cfg.get("memory_char_limit", DEFAULT_MEMORY_CHAR_LIMIT))
+        self.user_limit = int(mem_cfg.get("user_char_limit", DEFAULT_USER_CHAR_LIMIT))
+
+        if self.skill_conflict_mode not in SKILL_CONFLICT_MODES:
+            raise ValueError(
+                "Unknown skill conflict mode: "
+                + self.skill_conflict_mode
+                + ". Valid modes: "
+                + ", ".join(sorted(SKILL_CONFLICT_MODES))
+            )
+
+    def is_selected(self, option_id: str) -> bool:
+        return option_id in self.selected_options
+
+    # Option ids that mutate the Hermes config.yaml file.  Once any one of
+    # them records a conflict/error on config.yaml, subsequent ones are
+    # short-circuited to avoid partial writes.  Keep in sync with methods
+    # that call load_yaml_file(target_root / "config.yaml") + dump_yaml_file.
+    _CONFIG_MUTATING_OPTIONS = frozenset({
+        "model-config",
+        "tts-config",
+        "mcp-servers",
+        "plugins-config",
+        "cron-jobs",
+        "hooks-config",
+        "agent-config",
+        "gateway-config",
+        "session-config",
+        "full-providers",
+        "deep-channels",
+        "browser-config",
+        "tools-config",
+        "approvals-config",
+        "memory-backend",
+        "skills-config",
+        "ui-identity",
+        "logging-config",
+        "command-allowlist",
+    })
+
+    def record(
+        self,
+        kind: str,
+        source: Optional[Path],
+        destination: Optional[Path],
+        status: str,
+        reason: str = "",
+        **details: Any,
+    ) -> None:
+        sensitive = bool(details.pop("sensitive", False))
+        self.items.append(
+            ItemResult(
+                kind=kind,
+                source=str(source) if source else None,
+                destination=str(destination) if destination else None,
+                status=status,
+                reason=reason,
+                details=details,
+                sensitive=sensitive,
+            )
+        )
+        # Flip the config-block flag when a conflict/error occurs on a
+        # config.yaml write.  Later config-mutating options will skip rather
+        # than attempting a partial write.
+        if status in (STATUS_CONFLICT, STATUS_ERROR) and destination is not None:
+            dest_str = str(destination)
+            if dest_str.endswith("config.yaml") or dest_str.endswith("config.yml"):
+                self._config_apply_blocked = True
+
+    def source_candidate(self, *relative_paths: str) -> Optional[Path]:
+        for rel in relative_paths:
+            candidate = self.source_root / rel
+            if candidate.exists():
+                return candidate
+            # OpenClaw renamed workspace/ to workspace-main/ (and workspace-{agentId}
+            # for multi-agent).  Try the new path as a fallback.
+            if rel.startswith("workspace/"):
+                suffix = rel[len("workspace/"):]
+                for variant in ("workspace-main", "workspace-assistant"):
+                    alt = self.source_root / variant / suffix
+                    if alt.exists():
+                        return alt
+            elif rel.startswith("workspace.default/"):
+                suffix = rel[len("workspace.default/"):]
+                alt = self.source_root / "workspace-main" / suffix
+                if alt.exists():
+                    return alt
+
+        # Final fallback: check the configured workspace directory from
+        # agents.defaults.workspace in openclaw.json.  Users who started
+        # before the OpenClaw rebrand (when the project was named clawd /
+        # clawdbot) often have a custom workspace path outside ~/.openclaw/.
+        if self._custom_workspace:
+            for rel in relative_paths:
+                # Strip the leading "workspace/" or "workspace.default/"
+                # prefix to get the bare filename/subpath.
+                for prefix in ("workspace/", "workspace.default/"):
+                    if rel.startswith(prefix):
+                        suffix = rel[len(prefix):]
+                        alt = self._custom_workspace / suffix
+                        if alt.exists():
+                            return alt
+                        break
+
+        return None
+
+    def resolve_skill_destination(self, destination: Path) -> Path:
+        if self.skill_conflict_mode != "rename" or not destination.exists():
+            return destination
+
+        suffix = "-imported"
+        candidate = destination.with_name(destination.name + suffix)
+        counter = 2
+        while candidate.exists():
+            candidate = destination.with_name(f"{destination.name}{suffix}-{counter}")
+            counter += 1
+        return candidate
+
+    def migrate(self) -> Dict[str, Any]:
+        if not self.source_root.exists():
+            self.record("source", self.source_root, None, "error", "OpenClaw directory does not exist")
+            return self.build_report()
+
+        config = self.load_openclaw_config()
+
+        self.run_if_selected("soul", self.migrate_soul)
+        self.run_if_selected("workspace-agents", self.migrate_workspace_agents)
+        self.run_if_selected(
+            "memory",
+            lambda: self.migrate_memory(
+                self.source_candidate("workspace/MEMORY.md", "workspace.default/MEMORY.md"),
+                self.target_root / "memories" / "MEMORY.md",
+                self.memory_limit,
+                kind="memory",
+            ),
+        )
+        self.run_if_selected(
+            "user-profile",
+            lambda: self.migrate_memory(
+                self.source_candidate("workspace/USER.md", "workspace.default/USER.md"),
+                self.target_root / "memories" / "USER.md",
+                self.user_limit,
+                kind="user-profile",
+            ),
+        )
+        self.run_if_selected("messaging-settings", lambda: self.migrate_messaging_settings(config))
+        self.run_if_selected("secret-settings", lambda: self.handle_secret_settings(config))
+        self.run_if_selected("discord-settings", lambda: self.migrate_discord_settings(config))
+        self.run_if_selected("slack-settings", lambda: self.migrate_slack_settings(config))
+        self.run_if_selected("whatsapp-settings", lambda: self.migrate_whatsapp_settings(config))
+        self.run_if_selected("signal-settings", lambda: self.migrate_signal_settings(config))
+        self.run_if_selected("provider-keys", lambda: self.handle_provider_keys(config))
+        self.run_if_selected("model-config", lambda: self.migrate_model_config(config))
+        self.run_if_selected("tts-config", lambda: self.migrate_tts_config(config))
+        self.run_if_selected("command-allowlist", self.migrate_command_allowlist)
+        self.run_if_selected("skills", self.migrate_skills)
+        self.run_if_selected("shared-skills", self.migrate_shared_skills)
+        self.run_if_selected("daily-memory", self.migrate_daily_memory)
+        self.run_if_selected(
+            "tts-assets",
+            lambda: self.copy_tree_non_destructive(
+                self.source_candidate("workspace/tts"),
+                self.target_root / "tts",
+                kind="tts-assets",
+                ignore_dir_names={".venv", "generated", "__pycache__"},
+            ),
+        )
+        self.run_if_selected("archive", self.archive_docs)
+
+        # ── v2 migration modules ──────────────────────────────
+        self.run_if_selected("mcp-servers", lambda: self.migrate_mcp_servers(config))
+        self.run_if_selected("plugins-config", lambda: self.migrate_plugins_config(config))
+        self.run_if_selected("cron-jobs", lambda: self.migrate_cron_jobs(config))
+        self.run_if_selected("hooks-config", lambda: self.migrate_hooks_config(config))
+        self.run_if_selected("agent-config", lambda: self.migrate_agent_config(config))
+        self.run_if_selected("gateway-config", lambda: self.migrate_gateway_config(config))
+        self.run_if_selected("session-config", lambda: self.migrate_session_config(config))
+        self.run_if_selected("full-providers", lambda: self.migrate_full_providers(config))
+        self.run_if_selected("deep-channels", lambda: self.migrate_deep_channels(config))
+        self.run_if_selected("browser-config", lambda: self.migrate_browser_config(config))
+        self.run_if_selected("tools-config", lambda: self.migrate_tools_config(config))
+        self.run_if_selected("approvals-config", lambda: self.migrate_approvals_config(config))
+        self.run_if_selected("memory-backend", lambda: self.migrate_memory_backend(config))
+        self.run_if_selected("skills-config", lambda: self.migrate_skills_config(config))
+        self.run_if_selected("ui-identity", lambda: self.migrate_ui_identity(config))
+        self.run_if_selected("logging-config", lambda: self.migrate_logging_config(config))
+
+        # Generate migration notes
+        self.generate_migration_notes()
+
+        return self.build_report()
+
+    def run_if_selected(self, option_id: str, func) -> None:
+        if not self.is_selected(option_id):
+            meta = MIGRATION_OPTION_METADATA[option_id]
+            self.record(option_id, None, None, "skipped", "Not selected for this run", option_label=meta["label"])
+            return
+        # If a previous config.yaml write hit a conflict/error during apply,
+        # skip remaining config-mutating options rather than risk a partial
+        # write.  Dry-run mode never blocks — the user needs the full preview
+        # to decide how to proceed (re-run with --overwrite, etc.).
+        if (
+            self.execute
+            and self._config_apply_blocked
+            and option_id in self._CONFIG_MUTATING_OPTIONS
+        ):
+            meta = MIGRATION_OPTION_METADATA[option_id]
+            self.record(
+                option_id,
+                None,
+                None,
+                STATUS_SKIPPED,
+                REASON_BLOCKED_BY_APPLY_CONFLICT,
+                option_label=meta["label"],
+            )
+            return
+        func()
+
+    def build_report(self) -> Dict[str, Any]:
+        summary: Dict[str, int] = {
+            "migrated": 0,
+            "archived": 0,
+            "skipped": 0,
+            "conflict": 0,
+            "error": 0,
+        }
+        for item in self.items:
+            summary[item.status] = summary.get(item.status, 0) + 1
+
+        report = {
+            "timestamp": self.timestamp,
+            "mode": "execute" if self.execute else "dry-run",
+            "source_root": str(self.source_root),
+            "target_root": str(self.target_root),
+            "workspace_target": str(self.workspace_target) if self.workspace_target else None,
+            "output_dir": str(self.output_dir) if self.output_dir else None,
+            "migrate_secrets": self.migrate_secrets,
+            "preset": self.preset_name or None,
+            "skill_conflict_mode": self.skill_conflict_mode,
+            "selection": {
+                "selected": sorted(self.selected_options),
+                "preset": self.preset_name or None,
+                "skill_conflict_mode": self.skill_conflict_mode,
+                "available": [
+                    {"id": option_id, **meta}
+                    for option_id, meta in MIGRATION_OPTION_METADATA.items()
+                ],
+                "presets": [
+                    {"id": preset_id, "selected": sorted(option_ids)}
+                    for preset_id, option_ids in MIGRATION_PRESETS.items()
+                ],
+            },
+            "summary": summary,
+            "items": [asdict(item) for item in self.items],
+            "warnings": self._build_warnings(summary),
+            "next_steps": self._build_next_steps(summary),
+        }
+
+        if self.output_dir:
+            write_report(self.output_dir, report)
+
+        return report
+
+    def _build_warnings(self, summary: Dict[str, int]) -> List[str]:
+        """Structured warnings surfaced on the report for downstream consumers.
+
+        Modelled on OpenClaw's extensions/migrate-hermes/plan.ts warnings[].
+        Keep the messages actionable — they show up in summary.md and the
+        JSON report.
+        """
+        warnings: List[str] = []
+        if summary.get("conflict", 0) > 0:
+            warnings.append(
+                "Conflicts were found. Re-run with --overwrite to replace conflicting "
+                "targets after item-level backups."
+            )
+        if summary.get("error", 0) > 0:
+            warnings.append(
+                "One or more items failed. Inspect the report and re-run after fixing "
+                "the underlying cause."
+            )
+        if self._config_apply_blocked and self.execute:
+            warnings.append(
+                "A config.yaml write hit a conflict or error mid-apply; later config "
+                "items were skipped to avoid a partial write."
+            )
+        # Detect whether secrets were detected but not migrated.
+        provider_keys_skipped = any(
+            item.kind == "provider-keys" and item.status == STATUS_SKIPPED
+            for item in self.items
+        )
+        if provider_keys_skipped and not self.migrate_secrets:
+            warnings.append(
+                "API keys and other credentials were detected but not imported. "
+                "Re-run with --migrate-secrets to copy supported keys into the "
+                "Hermes env file."
+            )
+        return warnings
+
+    def _build_next_steps(self, summary: Dict[str, int]) -> List[str]:
+        """Human-readable next-step guidance baked into the report."""
+        if not self.execute:
+            return [
+                "Re-run without --dry-run to apply the migration.",
+                "Pass --overwrite to resolve conflicts, or --migrate-secrets to "
+                "include API keys.",
+            ]
+        steps: List[str] = []
+        if summary.get("migrated", 0) > 0:
+            steps.append(
+                "Review the migration report at "
+                f"{self.output_dir}/summary.md"
+                if self.output_dir
+                else "Review the migration report."
+            )
+            steps.append(
+                "Start a new Hermes session (or /reset) to pick up the imported config."
+            )
+        if summary.get("conflict", 0) > 0:
+            steps.append(
+                "Re-run with --overwrite to apply items that were blocked by conflicts."
+            )
+        return steps
+
+    def maybe_backup(self, path: Path) -> Optional[Path]:
+        if not self.execute or not self.backup_dir or not path.exists():
+            return None
+        return backup_existing(path, self.backup_dir)
+
+    def write_overflow_entries(self, kind: str, entries: Sequence[str]) -> Optional[Path]:
+        if not entries or not self.overflow_dir:
+            return None
+        self.overflow_dir.mkdir(parents=True, exist_ok=True)
+        filename = f"{kind.replace('-', '_')}_overflow.txt"
+        path = self.overflow_dir / filename
+        path.write_text("\n".join(entries) + "\n", encoding="utf-8")
+        return path
+
+    def copy_file(self, source: Path, destination: Path, kind: str,
+                  transform: Optional[Any] = None) -> None:
+        if not source or not source.exists():
+            return
+
+        if destination.exists():
+            if not transform and sha256_file(source) == sha256_file(destination):
+                self.record(kind, source, destination, "skipped", "Target already matches source")
+                return
+            if not self.overwrite:
+                self.record(kind, source, destination, "conflict", "Target exists and overwrite is disabled")
+                return
+
+        if self.execute:
+            backup_path = self.maybe_backup(destination)
+            ensure_parent(destination)
+            if transform:
+                content = read_text(source)
+                content = transform(content)
+                destination.write_text(content, encoding="utf-8")
+                shutil.copystat(source, destination)
+            else:
+                shutil.copy2(source, destination)
+            self.record(kind, source, destination, "migrated", backup=str(backup_path) if backup_path else None)
+        else:
+            self.record(kind, source, destination, "migrated", "Would copy")
+
+    def migrate_soul(self) -> None:
+        source = self.source_candidate("workspace/SOUL.md", "workspace.default/SOUL.md")
+        if not source:
+            self.record("soul", None, self.target_root / "SOUL.md", "skipped", "No OpenClaw SOUL.md found")
+            return
+        self.copy_file(source, self.target_root / "SOUL.md", kind="soul", transform=rebrand_text)
+
+    def migrate_workspace_agents(self) -> None:
+        source = self.source_candidate(
+            f"workspace/{WORKSPACE_INSTRUCTIONS_FILENAME}",
+            f"workspace.default/{WORKSPACE_INSTRUCTIONS_FILENAME}",
+        )
+        if source is None:
+            self.record("workspace-agents", "workspace/AGENTS.md", "", "skipped", "Source file not found")
+            return
+        if not self.workspace_target:
+            self.record("workspace-agents", source, None, "skipped", "No workspace target was provided")
+            return
+        destination = self.workspace_target / WORKSPACE_INSTRUCTIONS_FILENAME
+        self.copy_file(source, destination, kind="workspace-agents", transform=rebrand_text)
+
+    def migrate_memory(self, source: Optional[Path], destination: Path, limit: int, kind: str) -> None:
+        if not source or not source.exists():
+            self.record(kind, None, destination, "skipped", "Source file not found")
+            return
+
+        incoming = extract_markdown_entries(read_text(source))
+        if not incoming:
+            self.record(kind, source, destination, "skipped", "No importable entries found")
+            return
+        incoming = [rebrand_text(entry) for entry in incoming]
+
+        existing = parse_existing_memory_entries(destination)
+        merged, stats, overflowed = merge_entries(existing, incoming, limit)
+        details = {
+            "existing_entries": stats["existing"],
+            "added_entries": stats["added"],
+            "duplicate_entries": stats["duplicates"],
+            "overflowed_entries": stats["overflowed"],
+            "char_limit": limit,
+            "final_char_count": len(ENTRY_DELIMITER.join(merged)) if merged else 0,
+        }
+        overflow_file = self.write_overflow_entries(kind, overflowed)
+        if overflow_file is not None:
+            details["overflow_file"] = str(overflow_file)
+
+        if self.execute:
+            if stats["added"] == 0 and not overflowed:
+                self.record(kind, source, destination, "skipped", "No new entries to import", **details)
+                return
+            backup_path = self.maybe_backup(destination)
+            ensure_parent(destination)
+            destination.write_text(ENTRY_DELIMITER.join(merged) + ("\n" if merged else ""), encoding="utf-8")
+            self.record(
+                kind,
+                source,
+                destination,
+                "migrated",
+                backup=str(backup_path) if backup_path else "",
+                overflow_preview=overflowed[:5],
+                **details,
+            )
+        else:
+            self.record(kind, source, destination, "migrated", "Would merge entries", overflow_preview=overflowed[:5], **details)
+
+    def migrate_command_allowlist(self) -> None:
+        source = self.source_root / "exec-approvals.json"
+        destination = self.target_root / "config.yaml"
+        if not source.exists():
+            self.record("command-allowlist", None, destination, "skipped", "No OpenClaw exec approvals file found")
+            return
+        if yaml is None:
+            self.record("command-allowlist", source, destination, "error", "PyYAML is not available")
+            return
+
+        try:
+            data = json.loads(source.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            self.record("command-allowlist", source, destination, "error", f"Invalid JSON: {exc}")
+            return
+
+        patterns: List[str] = []
+        agents = data.get("agents", {})
+        if isinstance(agents, dict):
+            for agent_data in agents.values():
+                allowlist = agent_data.get("allowlist", []) if isinstance(agent_data, dict) else []
+                for entry in allowlist:
+                    pattern = entry.get("pattern") if isinstance(entry, dict) else None
+                    if pattern:
+                        patterns.append(pattern)
+
+        patterns = sorted(dict.fromkeys(patterns))
+        if not patterns:
+            self.record("command-allowlist", source, destination, "skipped", "No allowlist patterns found")
+            return
+        if not destination.exists():
+            self.record("command-allowlist", source, destination, "skipped", "Hermes config.yaml does not exist yet")
+            return
+
+        config = load_yaml_file(destination)
+        current = config.get("command_allowlist", [])
+        if not isinstance(current, list):
+            current = []
+        merged = sorted(dict.fromkeys(list(current) + patterns))
+        added = [pattern for pattern in merged if pattern not in current]
+        if not added:
+            self.record("command-allowlist", source, destination, "skipped", "All patterns already present")
+            return
+
+        if self.execute:
+            backup_path = self.maybe_backup(destination)
+            config["command_allowlist"] = merged
+            dump_yaml_file(destination, config)
+            self.record(
+                "command-allowlist",
+                source,
+                destination,
+                "migrated",
+                backup=str(backup_path) if backup_path else "",
+                added_patterns=added,
+            )
+        else:
+            self.record("command-allowlist", source, destination, "migrated", "Would merge patterns", added_patterns=added)
+
+    def load_openclaw_config(self) -> Dict[str, Any]:
+        # Check current name and legacy config filenames
+        for name in ("openclaw.json", "clawdbot.json", "moltbot.json"):
+            config_path = self.source_root / name
+            if config_path.exists():
+                try:
+                    data = json.loads(config_path.read_text(encoding="utf-8"))
+                    return data if isinstance(data, dict) else {}
+                except json.JSONDecodeError:
+                    continue
+        return {}
+
+    def load_openclaw_env(self) -> Dict[str, str]:
+        """Load the OpenClaw .env file for secrets that live there instead of config."""
+        return parse_env_file(self.source_root / ".env")
+
+    def merge_env_values(self, additions: Dict[str, str], kind: str, source: Path) -> None:
+        destination = self.target_root / ".env"
+        env_data = parse_env_file(destination)
+        added: Dict[str, str] = {}
+        conflicts: List[str] = []
+
+        for key, value in additions.items():
+            current = env_data.get(key)
+            if current == value:
+                continue
+            if current and not self.overwrite:
+                conflicts.append(key)
+                continue
+            env_data[key] = value
+            added[key] = value
+
+        if conflicts and not added:
+            self.record(kind, source, destination, "conflict", "Destination .env already has different values", conflicting_keys=conflicts)
+            return
+        if not conflicts and not added:
+            self.record(kind, source, destination, "skipped", "All env values already present")
+            return
+
+        if self.execute:
+            backup_path = self.maybe_backup(destination)
+            save_env_file(destination, env_data)
+            self.record(
+                kind,
+                source,
+                destination,
+                "migrated",
+                backup=str(backup_path) if backup_path else "",
+                added_keys=sorted(added.keys()),
+                conflicting_keys=conflicts,
+            )
+        else:
+            self.record(
+                kind,
+                source,
+                destination,
+                "migrated",
+                "Would merge env values",
+                added_keys=sorted(added.keys()),
+                conflicting_keys=conflicts,
+            )
+
+    def migrate_messaging_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        additions: Dict[str, str] = {}
+
+        workspace = (
+            config.get("agents", {})
+            .get("defaults", {})
+            .get("workspace")
+        )
+        if isinstance(workspace, str) and workspace.strip():
+            ws_path = workspace.strip()
+            # Skip if the workspace points inside the OpenClaw source directory —
+            # that path will be stale after migration and would cause the Hermes
+            # gateway to use the old OpenClaw workspace as its cwd, picking up
+            # OpenClaw's AGENTS.md, MEMORY.md, etc.
+            try:
+                inside_source = Path(ws_path).resolve().is_relative_to(self.source_root.resolve())
+            except (ValueError, OSError):
+                inside_source = False
+            if not inside_source:
+                additions["MESSAGING_CWD"] = ws_path
+
+        allowlist_path = self.source_root / "credentials" / "telegram-default-allowFrom.json"
+        if allowlist_path.exists():
+            try:
+                allow_data = json.loads(allowlist_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                self.record("messaging-settings", allowlist_path, self.target_root / ".env", "error", "Invalid JSON in Telegram allowlist file")
+            else:
+                allow_from = allow_data.get("allowFrom", [])
+                if isinstance(allow_from, list):
+                    users = [str(user).strip() for user in allow_from if str(user).strip()]
+                    if users:
+                        additions["TELEGRAM_ALLOWED_USERS"] = ",".join(users)
+
+        if additions:
+            self.merge_env_values(additions, "messaging-settings", self.source_root / "openclaw.json")
+        else:
+            self.record("messaging-settings", self.source_root / "openclaw.json", self.target_root / ".env", "skipped", "No Hermes-compatible messaging settings found")
+
+    def handle_secret_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        if self.migrate_secrets:
+            self.migrate_secret_settings(config)
+            return
+
+        config_path = self.source_root / "openclaw.json"
+        if config_path.exists():
+            self.record(
+                "secret-settings",
+                config_path,
+                self.target_root / ".env",
+                "skipped",
+                "Secret migration disabled. Re-run with --migrate-secrets to import allowlisted secrets.",
+                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
+            )
+        else:
+            self.record(
+                "secret-settings",
+                config_path,
+                self.target_root / ".env",
+                "skipped",
+                "OpenClaw config file not found",
+                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
+            )
+
+    def migrate_secret_settings(self, config: Dict[str, Any]) -> None:
+        secret_additions: Dict[str, str] = {}
+
+        tg_cfg = config.get("channels", {}).get("telegram", {})
+        telegram_token = self._get_channel_field(tg_cfg, "botToken") if isinstance(tg_cfg, dict) else None
+        if isinstance(telegram_token, str) and telegram_token.strip():
+            secret_additions["TELEGRAM_BOT_TOKEN"] = telegram_token.strip()
+
+        if secret_additions:
+            self.merge_env_values(secret_additions, "secret-settings", self.source_root / "openclaw.json")
+        else:
+            self.record(
+                "secret-settings",
+                self.source_root / "openclaw.json",
+                self.target_root / ".env",
+                "skipped",
+                "No allowlisted Hermes-compatible secrets found",
+                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
+            )
+
+    def _resolve_channel_secret(self, value: Any) -> Optional[str]:
+        """Resolve a channel config value that may be a SecretRef."""
+        return resolve_secret_input(value, self.load_openclaw_env())
+
+    @staticmethod
+    def _get_channel_field(ch_cfg: Dict[str, Any], field: str) -> Any:
+        """Get a field from channel config, checking both flat and accounts.default layout."""
+        val = ch_cfg.get(field)
+        if val is not None:
+            return val
+        accounts = ch_cfg.get("accounts")
+        if isinstance(accounts, dict):
+            default = accounts.get("default")
+            if isinstance(default, dict):
+                return default.get(field)
+        return None
+
+    def migrate_discord_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        additions: Dict[str, str] = {}
+        discord = config.get("channels", {}).get("discord", {})
+        if isinstance(discord, dict):
+            token = self._get_channel_field(discord, "token")
+            if isinstance(token, str) and token.strip():
+                additions["DISCORD_BOT_TOKEN"] = token.strip()
+            allow_from = self._get_channel_field(discord, "allowFrom") or []
+            if isinstance(allow_from, list):
+                users = [str(u).strip() for u in allow_from if str(u).strip()]
+                if users:
+                    additions["DISCORD_ALLOWED_USERS"] = ",".join(users)
+        if additions:
+            self.merge_env_values(additions, "discord-settings", self.source_root / "openclaw.json")
+        else:
+            self.record("discord-settings", self.source_root / "openclaw.json", self.target_root / ".env", "skipped", "No Discord settings found")
+
+    def migrate_slack_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        additions: Dict[str, str] = {}
+        slack = config.get("channels", {}).get("slack", {})
+        if isinstance(slack, dict):
+            bot_token = self._get_channel_field(slack, "botToken")
+            if isinstance(bot_token, str) and bot_token.strip():
+                additions["SLACK_BOT_TOKEN"] = bot_token.strip()
+            app_token = self._get_channel_field(slack, "appToken")
+            if isinstance(app_token, str) and app_token.strip():
+                additions["SLACK_APP_TOKEN"] = app_token.strip()
+            allow_from = self._get_channel_field(slack, "allowFrom") or []
+            if isinstance(allow_from, list):
+                users = [str(u).strip() for u in allow_from if str(u).strip()]
+                if users:
+                    additions["SLACK_ALLOWED_USERS"] = ",".join(users)
+        if additions:
+            self.merge_env_values(additions, "slack-settings", self.source_root / "openclaw.json")
+        else:
+            self.record("slack-settings", self.source_root / "openclaw.json", self.target_root / ".env", "skipped", "No Slack settings found")
+
+    def migrate_whatsapp_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        additions: Dict[str, str] = {}
+        whatsapp = config.get("channels", {}).get("whatsapp", {})
+        if isinstance(whatsapp, dict):
+            allow_from = self._get_channel_field(whatsapp, "allowFrom") or []
+            if isinstance(allow_from, list):
+                users = [str(u).strip() for u in allow_from if str(u).strip()]
+                if users:
+                    additions["WHATSAPP_ALLOWED_USERS"] = ",".join(users)
+        if additions:
+            self.merge_env_values(additions, "whatsapp-settings", self.source_root / "openclaw.json")
+        else:
+            self.record("whatsapp-settings", self.source_root / "openclaw.json", self.target_root / ".env", "skipped", "No WhatsApp settings found")
+
+    def migrate_signal_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        additions: Dict[str, str] = {}
+        signal = config.get("channels", {}).get("signal", {})
+        if isinstance(signal, dict):
+            account = self._get_channel_field(signal, "account")
+            if isinstance(account, str) and account.strip():
+                additions["SIGNAL_ACCOUNT"] = account.strip()
+            http_url = self._get_channel_field(signal, "httpUrl")
+            if isinstance(http_url, str) and http_url.strip():
+                additions["SIGNAL_HTTP_URL"] = http_url.strip()
+            allow_from = self._get_channel_field(signal, "allowFrom") or []
+            if isinstance(allow_from, list):
+                users = [str(u).strip() for u in allow_from if str(u).strip()]
+                if users:
+                    additions["SIGNAL_ALLOWED_USERS"] = ",".join(users)
+        if additions:
+            self.merge_env_values(additions, "signal-settings", self.source_root / "openclaw.json")
+        else:
+            self.record("signal-settings", self.source_root / "openclaw.json", self.target_root / ".env", "skipped", "No Signal settings found")
+
+    def handle_provider_keys(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        if not self.migrate_secrets:
+            config_path = self.source_root / "openclaw.json"
+            self.record(
+                "provider-keys",
+                config_path,
+                self.target_root / ".env",
+                "skipped",
+                "Secret migration disabled. Re-run with --migrate-secrets to import provider API keys.",
+                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
+            )
+            return
+        self.migrate_provider_keys(config)
+
+    def migrate_provider_keys(self, config: Dict[str, Any]) -> None:
+        secret_additions: Dict[str, str] = {}
+
+        # Extract provider API keys from models.providers
+        # Note: apiKey values can be strings, env templates, or SecretRef objects
+        openclaw_env = self.load_openclaw_env()
+        providers = config.get("models", {}).get("providers", {})
+        if isinstance(providers, dict):
+            for provider_name, provider_cfg in providers.items():
+                if not isinstance(provider_cfg, dict):
+                    continue
+                raw_key = provider_cfg.get("apiKey")
+                api_key = resolve_secret_input(raw_key, openclaw_env)
+                if not api_key:
+                    # Warn if a SecretRef with file/exec source was silently unresolvable
+                    if isinstance(raw_key, dict) and raw_key.get("source") in ("file", "exec"):
+                        self.record(
+                            "provider-keys",
+                            self.source_root / "openclaw.json",
+                            None,
+                            "skipped",
+                            f"Provider '{provider_name}' uses a {raw_key['source']}-backed SecretRef "
+                            f"that cannot be auto-migrated. Add this key manually via: hermes config set",
+                        )
+                    continue
+
+                base_url = provider_cfg.get("baseUrl", "")
+                api_type = provider_cfg.get("api", "")
+                env_var = None
+
+                # Match by baseUrl first
+                if isinstance(base_url, str):
+                    if "openrouter" in base_url.lower():
+                        env_var = "OPENROUTER_API_KEY"
+                    elif "openai.com" in base_url.lower():
+                        env_var = "OPENAI_API_KEY"
+                    elif "anthropic" in base_url.lower():
+                        env_var = "ANTHROPIC_API_KEY"
+
+                # Match by api type
+                if not env_var and isinstance(api_type, str) and api_type == "anthropic-messages":
+                    env_var = "ANTHROPIC_API_KEY"
+
+                # Match by provider name
+                if not env_var:
+                    name_lower = provider_name.lower()
+                    if name_lower == "openrouter":
+                        env_var = "OPENROUTER_API_KEY"
+                    elif "openai" in name_lower:
+                        env_var = "OPENAI_API_KEY"
+
+                if env_var:
+                    secret_additions[env_var] = api_key
+
+        # Extract TTS API keys
+        tts = config.get("messages", {}).get("tts", {})
+        if isinstance(tts, dict):
+            elevenlabs = tts.get("elevenlabs", {})
+            if isinstance(elevenlabs, dict):
+                el_key = elevenlabs.get("apiKey")
+                if isinstance(el_key, str) and el_key.strip():
+                    secret_additions["ELEVENLABS_API_KEY"] = el_key.strip()
+            openai_tts = tts.get("openai", {})
+            if isinstance(openai_tts, dict):
+                oai_key = openai_tts.get("apiKey")
+                if isinstance(oai_key, str) and oai_key.strip():
+                    secret_additions["VOICE_TOOLS_OPENAI_KEY"] = oai_key.strip()
+
+        # Also check the OpenClaw .env file — many users store keys there
+        # instead of inline in openclaw.json
+        openclaw_env = self.load_openclaw_env()
+        env_key_mapping = {
+            "OPENROUTER_API_KEY": "OPENROUTER_API_KEY",
+            "OPENAI_API_KEY": "OPENAI_API_KEY",
+            "ANTHROPIC_API_KEY": "ANTHROPIC_API_KEY",
+            "ELEVENLABS_API_KEY": "ELEVENLABS_API_KEY",
+            "TELEGRAM_BOT_TOKEN": "TELEGRAM_BOT_TOKEN",
+            "DEEPSEEK_API_KEY": "DEEPSEEK_API_KEY",
+            "GEMINI_API_KEY": "GEMINI_API_KEY",
+            "ZAI_API_KEY": "ZAI_API_KEY",
+            "MINIMAX_API_KEY": "MINIMAX_API_KEY",
+        }
+        for oc_key, hermes_key in env_key_mapping.items():
+            val = openclaw_env.get(oc_key, "").strip()
+            if val and hermes_key not in secret_additions:
+                secret_additions[hermes_key] = val
+
+        # Check the openclaw.json "env" sub-object — some OpenClaw setups
+        # store API keys here instead of in a separate .env file.
+        # Keys can be at env.<KEY> or env.vars.<KEY>.
+        json_env = config.get("env")
+        if isinstance(json_env, dict):
+            env_vars = json_env.get("vars")
+            sources = [json_env]
+            if isinstance(env_vars, dict):
+                sources.append(env_vars)
+            for src in sources:
+                for oc_key, hermes_key in env_key_mapping.items():
+                    val = src.get(oc_key)
+                    if isinstance(val, str) and val.strip() and hermes_key not in secret_additions:
+                        secret_additions[hermes_key] = val.strip()
+
+        # Check per-agent auth-profiles.json for additional credentials
+        auth_profiles_path = self.source_root / "agents" / "main" / "agent" / "auth-profiles.json"
+        if auth_profiles_path.exists():
+            try:
+                profiles = json.loads(auth_profiles_path.read_text(encoding="utf-8"))
+                if isinstance(profiles, dict):
+                    # auth-profiles.json wraps profiles in a "profiles" key
+                    profile_entries = profiles.get("profiles", profiles) if isinstance(profiles.get("profiles"), dict) else profiles
+                    for profile_name, profile_data in profile_entries.items():
+                        if not isinstance(profile_data, dict):
+                            continue
+                        # Canonical field is "key", "apiKey" is accepted as alias
+                        api_key = profile_data.get("key", "") or profile_data.get("apiKey", "")
+                        if not isinstance(api_key, str) or not api_key.strip():
+                            continue
+                        name_lower = profile_name.lower()
+                        if "openrouter" in name_lower and "OPENROUTER_API_KEY" not in secret_additions:
+                            secret_additions["OPENROUTER_API_KEY"] = api_key.strip()
+                        elif "openai" in name_lower and "OPENAI_API_KEY" not in secret_additions:
+                            secret_additions["OPENAI_API_KEY"] = api_key.strip()
+                        elif "anthropic" in name_lower and "ANTHROPIC_API_KEY" not in secret_additions:
+                            secret_additions["ANTHROPIC_API_KEY"] = api_key.strip()
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        if secret_additions:
+            self.merge_env_values(secret_additions, "provider-keys", self.source_root / "openclaw.json")
+        else:
+            self.record(
+                "provider-keys",
+                self.source_root / "openclaw.json",
+                self.target_root / ".env",
+                "skipped",
+                "No provider API keys found",
+                supported_targets=sorted(SUPPORTED_SECRET_TARGETS),
+            )
+
+    def migrate_model_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        destination = self.target_root / "config.yaml"
+        source_path = self.source_root / "openclaw.json"
+
+        model_value = config.get("agents", {}).get("defaults", {}).get("model")
+        if model_value is None:
+            self.record("model-config", source_path, destination, "skipped", "No default model found in OpenClaw config")
+            return
+
+        if isinstance(model_value, dict):
+            model_str = model_value.get("primary")
+        else:
+            model_str = model_value
+
+        if not isinstance(model_str, str) or not model_str.strip():
+            self.record("model-config", source_path, destination, "skipped", "Default model value is empty or invalid")
+            return
+
+        model_str = model_str.strip()
+
+        # Resolve a model alias against the OpenClaw model catalog.
+        # OpenClaw stores agents.defaults.model as either a bare string or
+        # {"primary": "<value>"}, and that value can be either:
+        #   - a full provider/model API ID (e.g. "anthropic/claude-opus-4-6"), or
+        #   - a display alias (e.g. "Claude Opus 4.6") that maps to one.
+        # The catalog at agents.defaults.models is keyed by the full
+        # provider/model API ID with an "alias" field on the value, e.g.:
+        #   {"anthropic/claude-opus-4-6": {"alias": "Claude Opus 4.6"}}
+        # If model_str matches an alias in the catalog, rewrite it to the
+        # catalog key (the real API ID).  If it's already an API ID or has
+        # no catalog match, leave it alone and let downstream pass it through.
+        model_catalog = config.get("agents", {}).get("defaults", {}).get("models", {})
+        if isinstance(model_catalog, dict) and model_str not in model_catalog:
+            for api_id, entry in model_catalog.items():
+                if not isinstance(api_id, str):
+                    continue
+                if isinstance(entry, dict) and entry.get("alias") == model_str:
+                    model_str = api_id
+                    break
+                if isinstance(entry, str) and entry == model_str:
+                    model_str = api_id
+                    break
+
+        if yaml is None:
+            self.record("model-config", source_path, destination, "error", "PyYAML is not available")
+            return
+
+        hermes_config = load_yaml_file(destination)
+        current_model = hermes_config.get("model")
+        if current_model == model_str:
+            self.record("model-config", source_path, destination, "skipped", "Model already set to the same value")
+            return
+        if current_model and not self.overwrite:
+            self.record("model-config", source_path, destination, "conflict", "Model already set and overwrite is disabled", current=current_model, incoming=model_str)
+            return
+
+        if self.execute:
+            backup_path = self.maybe_backup(destination)
+            existing_model = hermes_config.get("model")
+            if isinstance(existing_model, dict):
+                existing_model["default"] = model_str
+            else:
+                hermes_config["model"] = {"default": model_str}
+            dump_yaml_file(destination, hermes_config)
+            self.record("model-config", source_path, destination, "migrated", backup=str(backup_path) if backup_path else "", model=model_str)
+        else:
+            self.record("model-config", source_path, destination, "migrated", "Would set model", model=model_str)
+
+    def migrate_tts_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        destination = self.target_root / "config.yaml"
+        source_path = self.source_root / "openclaw.json"
+
+        tts = config.get("messages", {}).get("tts", {})
+        if not isinstance(tts, dict) or not tts:
+            self.record("tts-config", source_path, destination, "skipped", "No TTS configuration found in OpenClaw config")
+            return
+
+        if yaml is None:
+            self.record("tts-config", source_path, destination, "error", "PyYAML is not available")
+            return
+
+        tts_data: Dict[str, Any] = {}
+
+        provider = tts.get("provider")
+        if isinstance(provider, str) and provider in ("elevenlabs", "openai", "edge", "microsoft"):
+            # OpenClaw renamed "edge" to "microsoft"; Hermes still uses "edge"
+            tts_data["provider"] = "edge" if provider == "microsoft" else provider
+
+        # TTS provider settings live under messages.tts.providers.{provider}
+        # in OpenClaw (not messages.tts.elevenlabs directly)
+        providers = tts.get("providers") or {}
+
+        # Also check the top-level "talk" config which has provider settings too
+        talk_cfg = (config or self.load_openclaw_config()).get("talk") or {}
+        talk_providers = talk_cfg.get("providers") or {}
+
+        # Merge: messages.tts.providers takes priority, then talk.providers,
+        # then legacy flat keys (messages.tts.elevenlabs, etc.)
+        elevenlabs = (
+            (providers.get("elevenlabs") or {})
+            if isinstance(providers.get("elevenlabs"), dict) else
+            (talk_providers.get("elevenlabs") or {})
+            if isinstance(talk_providers.get("elevenlabs"), dict) else
+            (tts.get("elevenlabs") or {})
+        )
+        if isinstance(elevenlabs, dict):
+            el_settings: Dict[str, str] = {}
+            voice_id = elevenlabs.get("voiceId") or talk_cfg.get("voiceId")
+            if isinstance(voice_id, str) and voice_id.strip():
+                el_settings["voice_id"] = voice_id.strip()
+            model_id = elevenlabs.get("modelId") or talk_cfg.get("modelId")
+            if isinstance(model_id, str) and model_id.strip():
+                el_settings["model_id"] = model_id.strip()
+            if el_settings:
+                tts_data["elevenlabs"] = el_settings
+
+        openai_tts = (
+            (providers.get("openai") or {})
+            if isinstance(providers.get("openai"), dict) else
+            (talk_providers.get("openai") or {})
+            if isinstance(talk_providers.get("openai"), dict) else
+            (tts.get("openai") or {})
+        )
+        if isinstance(openai_tts, dict):
+            oai_settings: Dict[str, str] = {}
+            oai_model = openai_tts.get("model") or openai_tts.get("modelId")
+            if isinstance(oai_model, str) and oai_model.strip():
+                oai_settings["model"] = oai_model.strip()
+            oai_voice = openai_tts.get("voice")
+            if isinstance(oai_voice, str) and oai_voice.strip():
+                oai_settings["voice"] = oai_voice.strip()
+            if oai_settings:
+                tts_data["openai"] = oai_settings
+
+        edge_tts = (
+            (providers.get("edge") or providers.get("microsoft") or {})
+            if isinstance(providers.get("edge"), dict) or isinstance(providers.get("microsoft"), dict) else
+            (tts.get("edge") or tts.get("microsoft") or {})
+        )
+        if isinstance(edge_tts, dict):
+            edge_voice = edge_tts.get("voice")
+            if isinstance(edge_voice, str) and edge_voice.strip():
+                tts_data["edge"] = {"voice": edge_voice.strip()}
+
+        if not tts_data:
+            self.record("tts-config", source_path, destination, "skipped", "No compatible TTS settings found")
+            return
+
+        hermes_config = load_yaml_file(destination)
+        existing_tts = hermes_config.get("tts", {})
+        if not isinstance(existing_tts, dict):
+            existing_tts = {}
+
+        if self.execute:
+            backup_path = self.maybe_backup(destination)
+            merged_tts = dict(existing_tts)
+            for key, value in tts_data.items():
+                if isinstance(value, dict) and isinstance(merged_tts.get(key), dict):
+                    merged_tts[key] = {**merged_tts[key], **value}
+                else:
+                    merged_tts[key] = value
+            hermes_config["tts"] = merged_tts
+            dump_yaml_file(destination, hermes_config)
+            self.record("tts-config", source_path, destination, "migrated", backup=str(backup_path) if backup_path else "", settings=list(tts_data.keys()))
+        else:
+            self.record("tts-config", source_path, destination, "migrated", "Would set TTS config", settings=list(tts_data.keys()))
+
+    def migrate_shared_skills(self) -> None:
+        # Check all OpenClaw skill sources: managed, personal, project-level
+        skill_sources = [
+            (self.source_root / "skills", "shared-skills", "managed skills"),
+            (Path.home() / ".agents" / "skills", "personal-skills", "personal cross-project skills"),
+            (self.source_root / "workspace" / ".agents" / "skills", "project-skills", "project-level shared skills"),
+            (self.source_root / "workspace.default" / ".agents" / "skills", "project-skills", "project-level shared skills"),
+        ]
+        found_any = False
+        for source_root, kind_label, desc in skill_sources:
+            if source_root.exists():
+                found_any = True
+                self._import_skill_directory(source_root, kind_label, desc)
+        if not found_any:
+            destination_root = self.target_root / "skills" / SKILL_CATEGORY_DIRNAME
+            self.record("shared-skills", None, destination_root, "skipped", "No shared OpenClaw skills directories found")
+
+    def _import_skill_directory(self, source_root: Path, kind_label: str, desc: str) -> None:
+        """Import skills from a single source directory into openclaw-imports."""
+        destination_root = self.target_root / "skills" / SKILL_CATEGORY_DIRNAME
+
+        skill_dirs = [p for p in sorted(source_root.iterdir()) if p.is_dir() and (p / "SKILL.md").exists()]
+        if not skill_dirs:
+            self.record(kind_label, source_root, destination_root, "skipped", f"No skills with SKILL.md found in {desc}")
+            return
+
+        for skill_dir in skill_dirs:
+            destination = destination_root / skill_dir.name
+            final_destination = destination
+            if destination.exists():
+                if self.skill_conflict_mode == "skip":
+                    self.record(kind_label, skill_dir, destination, "conflict", "Destination skill already exists")
+                    continue
+                if self.skill_conflict_mode == "rename":
+                    final_destination = self.resolve_skill_destination(destination)
+            if self.execute:
+                backup_path = None
+                if final_destination == destination and destination.exists():
+                    backup_path = self.maybe_backup(destination)
+                final_destination.parent.mkdir(parents=True, exist_ok=True)
+                if final_destination == destination and destination.exists():
+                    shutil.rmtree(destination)
+                shutil.copytree(skill_dir, final_destination)
+                details: Dict[str, Any] = {"backup": str(backup_path) if backup_path else ""}
+                if final_destination != destination:
+                    details["renamed_from"] = str(destination)
+                self.record(kind_label, skill_dir, final_destination, "migrated", **details)
+            else:
+                if final_destination != destination:
+                    self.record(
+                        kind_label,
+                        skill_dir,
+                        final_destination,
+                        "migrated",
+                        f"Would copy {desc} directory under a renamed folder",
+                        renamed_from=str(destination),
+                    )
+                else:
+                    self.record(kind_label, skill_dir, final_destination, "migrated", f"Would copy {desc} directory")
+
+        desc_path = destination_root / "DESCRIPTION.md"
+        if self.execute:
+            desc_path.parent.mkdir(parents=True, exist_ok=True)
+            if not desc_path.exists():
+                desc_path.write_text(SKILL_CATEGORY_DESCRIPTION + "\n", encoding="utf-8")
+        elif not desc_path.exists():
+            self.record("shared-skill-category", None, desc_path, "migrated", "Would create category description")
+
+    def migrate_daily_memory(self) -> None:
+        source_dir = self.source_candidate("workspace/memory")
+        destination = self.target_root / "memories" / "MEMORY.md"
+        if not source_dir or not source_dir.is_dir():
+            self.record("daily-memory", None, destination, "skipped", "No workspace/memory/ directory found")
+            return
+
+        md_files = sorted(p for p in source_dir.iterdir() if p.is_file() and p.suffix == ".md")
+        if not md_files:
+            self.record("daily-memory", source_dir, destination, "skipped", "No .md files found in workspace/memory/")
+            return
+
+        all_incoming: List[str] = []
+        for md_file in md_files:
+            entries = extract_markdown_entries(read_text(md_file))
+            all_incoming.extend(entries)
+
+        if not all_incoming:
+            self.record("daily-memory", source_dir, destination, "skipped", "No importable entries found in daily memory files")
+            return
+        all_incoming = [rebrand_text(entry) for entry in all_incoming]
+
+        existing = parse_existing_memory_entries(destination)
+        merged, stats, overflowed = merge_entries(existing, all_incoming, self.memory_limit)
+        details = {
+            "source_files": len(md_files),
+            "existing_entries": stats["existing"],
+            "added_entries": stats["added"],
+            "duplicate_entries": stats["duplicates"],
+            "overflowed_entries": stats["overflowed"],
+            "char_limit": self.memory_limit,
+            "final_char_count": len(ENTRY_DELIMITER.join(merged)) if merged else 0,
+        }
+        overflow_file = self.write_overflow_entries("daily-memory", overflowed)
+        if overflow_file is not None:
+            details["overflow_file"] = str(overflow_file)
+
+        if self.execute:
+            if stats["added"] == 0 and not overflowed:
+                self.record("daily-memory", source_dir, destination, "skipped", "No new entries to import", **details)
+                return
+            backup_path = self.maybe_backup(destination)
+            ensure_parent(destination)
+            destination.write_text(ENTRY_DELIMITER.join(merged) + ("\n" if merged else ""), encoding="utf-8")
+            self.record(
+                "daily-memory",
+                source_dir,
+                destination,
+                "migrated",
+                backup=str(backup_path) if backup_path else "",
+                overflow_preview=overflowed[:5],
+                **details,
+            )
+        else:
+            self.record("daily-memory", source_dir, destination, "migrated", "Would merge daily memory entries", overflow_preview=overflowed[:5], **details)
+
+    def migrate_skills(self) -> None:
+        source_root = self.source_candidate("workspace/skills")
+        destination_root = self.target_root / "skills" / SKILL_CATEGORY_DIRNAME
+        if not source_root or not source_root.exists():
+            self.record("skills", None, destination_root, "skipped", "No OpenClaw skills directory found")
+            return
+
+        skill_dirs = [p for p in sorted(source_root.iterdir()) if p.is_dir() and (p / "SKILL.md").exists()]
+        if not skill_dirs:
+            self.record("skills", source_root, destination_root, "skipped", "No skills with SKILL.md found")
+            return
+
+        for skill_dir in skill_dirs:
+            destination = destination_root / skill_dir.name
+            final_destination = destination
+            if destination.exists():
+                if self.skill_conflict_mode == "skip":
+                    self.record("skill", skill_dir, destination, "conflict", "Destination skill already exists")
+                    continue
+                if self.skill_conflict_mode == "rename":
+                    final_destination = self.resolve_skill_destination(destination)
+            if self.execute:
+                backup_path = None
+                if final_destination == destination and destination.exists():
+                    backup_path = self.maybe_backup(destination)
+                final_destination.parent.mkdir(parents=True, exist_ok=True)
+                if final_destination == destination and destination.exists():
+                    shutil.rmtree(destination)
+                shutil.copytree(skill_dir, final_destination)
+                details: Dict[str, Any] = {"backup": str(backup_path) if backup_path else ""}
+                if final_destination != destination:
+                    details["renamed_from"] = str(destination)
+                self.record("skill", skill_dir, final_destination, "migrated", **details)
+            else:
+                if final_destination != destination:
+                    self.record(
+                        "skill",
+                        skill_dir,
+                        final_destination,
+                        "migrated",
+                        "Would copy skill directory under a renamed folder",
+                        renamed_from=str(destination),
+                    )
+                else:
+                    self.record("skill", skill_dir, final_destination, "migrated", "Would copy skill directory")
+
+        desc_path = destination_root / "DESCRIPTION.md"
+        if self.execute:
+            desc_path.parent.mkdir(parents=True, exist_ok=True)
+            if not desc_path.exists():
+                desc_path.write_text(SKILL_CATEGORY_DESCRIPTION + "\n", encoding="utf-8")
+        elif not desc_path.exists():
+            self.record("skill-category", None, desc_path, "migrated", "Would create category description")
+
+    def copy_tree_non_destructive(
+        self,
+        source_root: Optional[Path],
+        destination_root: Path,
+        kind: str,
+        ignore_dir_names: Optional[set[str]] = None,
+    ) -> None:
+        if not source_root or not source_root.exists():
+            self.record(kind, None, destination_root, "skipped", "Source directory not found")
+            return
+
+        ignore_dir_names = ignore_dir_names or set()
+        files = [
+            p
+            for p in source_root.rglob("*")
+            if p.is_file() and not any(part in ignore_dir_names for part in p.relative_to(source_root).parts[:-1])
+        ]
+        if not files:
+            self.record(kind, source_root, destination_root, "skipped", "No files found")
+            return
+
+        copied = 0
+        skipped = 0
+        conflicts = 0
+
+        for source in files:
+            rel = source.relative_to(source_root)
+            destination = destination_root / rel
+            if destination.exists():
+                if sha256_file(source) == sha256_file(destination):
+                    skipped += 1
+                    continue
+                if not self.overwrite:
+                    conflicts += 1
+                    self.record(kind, source, destination, "conflict", "Destination file already exists")
+                    continue
+
+            if self.execute:
+                self.maybe_backup(destination)
+                ensure_parent(destination)
+                shutil.copy2(source, destination)
+            copied += 1
+
+        status = "migrated" if copied else "skipped"
+        reason = ""
+        if not copied and conflicts:
+            status = "conflict"
+            reason = "All candidate files conflicted with existing destination files"
+        elif not copied:
+            reason = "No new files to copy"
+
+        self.record(kind, source_root, destination_root, status, reason, copied_files=copied, unchanged_files=skipped, conflicts=conflicts)
+
+    def archive_docs(self) -> None:
+        candidates = [
+            self.source_candidate("workspace/IDENTITY.md", "workspace.default/IDENTITY.md"),
+            self.source_candidate("workspace/TOOLS.md", "workspace.default/TOOLS.md"),
+            self.source_candidate("workspace/HEARTBEAT.md", "workspace.default/HEARTBEAT.md"),
+            self.source_candidate("workspace/BOOTSTRAP.md", "workspace.default/BOOTSTRAP.md"),
+        ]
+        for candidate in candidates:
+            if candidate:
+                self.archive_path(candidate, reason="No direct Hermes destination; archived for manual review")
+
+        for rel in ("workspace/.learnings", "workspace/memory"):
+            candidate = self.source_root / rel
+            if candidate.exists():
+                self.archive_path(candidate, reason="No direct Hermes destination; archived for manual review")
+
+        partially_extracted = [
+            ("openclaw.json", "Selected Hermes-compatible values were extracted; raw OpenClaw config was not copied."),
+            ("credentials/telegram-default-allowFrom.json", "Selected Hermes-compatible values were extracted; raw credentials file was not copied."),
+        ]
+        for rel, reason in partially_extracted:
+            candidate = self.source_root / rel
+            if candidate.exists():
+                self.record("raw-config-skip", candidate, None, "skipped", reason)
+
+        skipped_sensitive = [
+            "memory/main.sqlite",
+            "credentials",
+            "devices",
+            "identity",
+            "workspace.zip",
+        ]
+        for rel in skipped_sensitive:
+            candidate = self.source_root / rel
+            if candidate.exists():
+                self.record("sensitive-skip", candidate, None, "skipped", "Contains secrets, binary state, or product-specific runtime data")
+
+    def archive_path(self, source: Path, reason: str) -> None:
+        destination = self.archive_dir / relative_label(source, self.source_root) if self.archive_dir else None
+        if self.execute and destination is not None:
+            ensure_parent(destination)
+            if source.is_dir():
+                shutil.copytree(source, destination, dirs_exist_ok=True)
+            else:
+                shutil.copy2(source, destination)
+            self.record("archive", source, destination, "archived", reason)
+        else:
+            self.record("archive", source, destination, "archived", reason)
+
+    # ── MCP servers ─────────────────────────────────────────────
+    def migrate_mcp_servers(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        mcp_raw = (config.get("mcp") or {}).get("servers") or {}
+        if not mcp_raw:
+            self.record("mcp-servers", None, None, "skipped", "No MCP servers found in OpenClaw config")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        existing_mcp = hermes_cfg.get("mcp_servers") or {}
+        added = 0
+
+        for name, srv in mcp_raw.items():
+            if not isinstance(srv, dict):
+                continue
+            if name in existing_mcp and not self.overwrite:
+                self.record("mcp-servers", f"mcp.servers.{name}", f"mcp_servers.{name}", "conflict",
+                            "MCP server already exists in Hermes config")
+                continue
+
+            hermes_srv: Dict[str, Any] = {}
+            # STDIO transport
+            if srv.get("command"):
+                hermes_srv["command"] = srv["command"]
+                if srv.get("args"):
+                    hermes_srv["args"] = srv["args"]
+                if srv.get("env"):
+                    hermes_srv["env"] = srv["env"]
+                if srv.get("cwd"):
+                    hermes_srv["cwd"] = srv["cwd"]
+            # HTTP/SSE transport
+            if srv.get("url"):
+                hermes_srv["url"] = srv["url"]
+                if srv.get("headers"):
+                    hermes_srv["headers"] = srv["headers"]
+                if srv.get("auth"):
+                    hermes_srv["auth"] = srv["auth"]
+            # Common fields
+            if srv.get("enabled") is False:
+                hermes_srv["enabled"] = False
+            if srv.get("timeout"):
+                hermes_srv["timeout"] = srv["timeout"]
+            if srv.get("connectTimeout"):
+                hermes_srv["connect_timeout"] = srv["connectTimeout"]
+            # Tool filtering
+            tools_cfg = srv.get("tools") or {}
+            if tools_cfg.get("include") or tools_cfg.get("exclude"):
+                hermes_srv["tools"] = {}
+                if tools_cfg.get("include"):
+                    hermes_srv["tools"]["include"] = tools_cfg["include"]
+                if tools_cfg.get("exclude"):
+                    hermes_srv["tools"]["exclude"] = tools_cfg["exclude"]
+            # Sampling
+            sampling = srv.get("sampling")
+            if sampling and isinstance(sampling, dict):
+                hermes_srv["sampling"] = {
+                    k: v for k, v in {
+                        "enabled": sampling.get("enabled"),
+                        "model": sampling.get("model"),
+                        "max_tokens_cap": sampling.get("maxTokensCap") or sampling.get("max_tokens_cap"),
+                        "timeout": sampling.get("timeout"),
+                        "max_rpm": sampling.get("maxRpm") or sampling.get("max_rpm"),
+                    }.items() if v is not None
+                }
+
+            existing_mcp[name] = hermes_srv
+            added += 1
+            self.record("mcp-servers", f"mcp.servers.{name}", f"config.yaml mcp_servers.{name}",
+                        "migrated", servers_added=added)
+
+        if added > 0 and self.execute:
+            self.maybe_backup(hermes_cfg_path)
+            hermes_cfg["mcp_servers"] = existing_mcp
+            dump_yaml_file(hermes_cfg_path, hermes_cfg)
+
+    # ── Plugins ───────────────────────────────────────────────
+    def migrate_plugins_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        plugins = config.get("plugins") or {}
+        if not plugins:
+            self.record("plugins-config", None, None, "skipped", "No plugins configuration found")
+            return
+
+        # Archive the full plugins config
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "plugins-config.json"
+            dest.write_text(json.dumps(plugins, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("plugins-config", "openclaw.json plugins.*", str(dest), "archived",
+                        "Plugins config archived for manual review")
+        else:
+            self.record("plugins-config", "openclaw.json plugins.*", "archive/plugins-config.json",
+                        "archived" if not self.execute else "migrated", "Would archive plugins config")
+
+        # Copy extensions directory if it exists
+        ext_dir = self.source_root / "extensions"
+        if ext_dir.is_dir() and self.archive_dir:
+            dest_ext = self.archive_dir / "extensions"
+            if self.execute:
+                shutil.copytree(ext_dir, dest_ext, dirs_exist_ok=True)
+            self.record("plugins-config", str(ext_dir), str(dest_ext), "archived",
+                        "Extensions directory archived")
+
+        # Extract any plugin env vars
+        entries = plugins.get("entries") or {}
+        for plugin_name, plugin_cfg in entries.items():
+            if isinstance(plugin_cfg, dict):
+                env_vars = plugin_cfg.get("env") or {}
+                api_key = plugin_cfg.get("apiKey")
+                if api_key and self.migrate_secrets:
+                    env_key = f"PLUGIN_{plugin_name.upper().replace('-', '_')}_API_KEY"
+                    self._set_env_var(env_key, api_key, f"plugins.entries.{plugin_name}.apiKey")
+
+    # ── Cron jobs ─────────────────────────────────────────────
+    def migrate_cron_jobs(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        cron = config.get("cron") or {}
+        cron_store = self.source_root / "cron"
+        found_any = False
+
+        # Archive the full cron config when present
+        if cron:
+            found_any = True
+            if self.archive_dir and self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "cron-config.json"
+                dest.write_text(json.dumps(cron, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+                self.record("cron-jobs", "openclaw.json cron.*", str(dest), "archived",
+                            "Cron config archived. Use 'hermes cron' to recreate jobs manually.")
+            else:
+                self.record("cron-jobs", "openclaw.json cron.*", "archive/cron-config.json",
+                            "archived", "Would archive cron config")
+
+        # Also check for cron store files even when config.cron is missing
+        if cron_store.is_dir() and self.archive_dir:
+            found_any = True
+            dest_cron = self.archive_dir / "cron-store"
+            if self.execute:
+                shutil.copytree(cron_store, dest_cron, dirs_exist_ok=True)
+            self.record("cron-jobs", str(cron_store), str(dest_cron), "archived",
+                        "Cron job store archived")
+
+        if not found_any:
+            self.record("cron-jobs", None, None, "skipped", "No cron configuration found")
+
+    # ── Hooks ─────────────────────────────────────────────────
+    def migrate_hooks_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        hooks = config.get("hooks") or {}
+        if not hooks:
+            self.record("hooks-config", None, None, "skipped", "No hooks configuration found")
+            return
+
+        # Archive the full hooks config
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "hooks-config.json"
+            dest.write_text(json.dumps(hooks, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("hooks-config", "openclaw.json hooks.*", str(dest), "archived",
+                        "Hooks config archived for manual review")
+        else:
+            self.record("hooks-config", "openclaw.json hooks.*", "archive/hooks-config.json",
+                        "archived", "Would archive hooks config")
+
+        # Copy workspace hooks directory
+        for ws_name in ("workspace", "workspace.default"):
+            hooks_dir = self.source_root / ws_name / "hooks"
+            if hooks_dir.is_dir() and self.archive_dir:
+                dest_hooks = self.archive_dir / "workspace-hooks"
+                if self.execute:
+                    shutil.copytree(hooks_dir, dest_hooks, dirs_exist_ok=True)
+                self.record("hooks-config", str(hooks_dir), str(dest_hooks), "archived",
+                            "Workspace hooks directory archived")
+                break
+
+    # ── Agent config ──────────────────────────────────────────
+    def migrate_agent_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        agents = config.get("agents") or {}
+        defaults = agents.get("defaults") or {}
+        agent_list = agents.get("list") or []
+
+        if not defaults and not agent_list:
+            self.record("agent-config", None, None, "skipped", "No agent configuration found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        changes = False
+
+        # Map agent defaults
+        agent_cfg = hermes_cfg.get("agent") or {}
+        if defaults.get("contextTokens"):
+            # No direct mapping but useful context
+            pass
+        if defaults.get("timeoutSeconds"):
+            agent_cfg["max_turns"] = min(defaults["timeoutSeconds"] // 10, 200)
+            changes = True
+        if defaults.get("verboseDefault"):
+            agent_cfg["verbose"] = defaults["verboseDefault"]
+            changes = True
+        if defaults.get("thinkingDefault"):
+            # Map OpenClaw thinking -> Hermes reasoning_effort
+            thinking = defaults["thinkingDefault"]
+            if thinking in ("always", "high", "xhigh"):
+                agent_cfg["reasoning_effort"] = "high"
+            elif thinking in ("auto", "medium", "adaptive"):
+                agent_cfg["reasoning_effort"] = "medium"
+            elif thinking in ("off", "low", "none", "minimal"):
+                agent_cfg["reasoning_effort"] = "low"
+            changes = True
+
+        # Map compaction -> compression
+        compaction = defaults.get("compaction") or {}
+        if compaction:
+            compression = hermes_cfg.get("compression") or {}
+            if compaction.get("mode") == "off":
+                compression["enabled"] = False
+            else:
+                compression["enabled"] = True
+            if compaction.get("timeout"):
+                pass  # No direct mapping
+            if compaction.get("model"):
+                aux = hermes_cfg.setdefault("auxiliary", {})
+                aux_comp = aux.setdefault("compression", {})
+                aux_comp["model"] = compaction["model"]
+            hermes_cfg["compression"] = compression
+            changes = True
+
+        # Map humanDelay
+        human_delay = defaults.get("humanDelay") or {}
+        if human_delay:
+            hd = hermes_cfg.get("human_delay") or {}
+            hd_mode = human_delay.get("mode") or ("natural" if human_delay.get("enabled") else None)
+            if hd_mode and hd_mode != "off":
+                hd["mode"] = hd_mode
+            if human_delay.get("minMs"):
+                hd["min_ms"] = human_delay["minMs"]
+            if human_delay.get("maxMs"):
+                hd["max_ms"] = human_delay["maxMs"]
+            hermes_cfg["human_delay"] = hd
+            changes = True
+
+        # Map userTimezone
+        if defaults.get("userTimezone"):
+            hermes_cfg["timezone"] = defaults["userTimezone"]
+            changes = True
+
+        # Map terminal/exec settings
+        exec_cfg = (config.get("tools") or {}).get("exec") or {}
+        if exec_cfg:
+            terminal_cfg = hermes_cfg.get("terminal") or {}
+            if exec_cfg.get("timeoutSec") or exec_cfg.get("timeout"):
+                terminal_cfg["timeout"] = exec_cfg.get("timeoutSec") or exec_cfg.get("timeout")
+                changes = True
+            hermes_cfg["terminal"] = terminal_cfg
+
+        # Map sandbox -> terminal docker settings
+        sandbox = defaults.get("sandbox") or {}
+        if sandbox and sandbox.get("backend") == "docker":
+            terminal_cfg = hermes_cfg.get("terminal") or {}
+            terminal_cfg["backend"] = "docker"
+            if sandbox.get("docker", {}).get("image"):
+                terminal_cfg["docker_image"] = sandbox["docker"]["image"]
+            hermes_cfg["terminal"] = terminal_cfg
+            changes = True
+
+        if changes:
+            hermes_cfg["agent"] = agent_cfg
+            if self.execute:
+                self.maybe_backup(hermes_cfg_path)
+                dump_yaml_file(hermes_cfg_path, hermes_cfg)
+            self.record("agent-config", "openclaw.json agents.defaults", "config.yaml agent/compression/terminal",
+                        "migrated", "Agent defaults mapped to Hermes config")
+
+        # Archive multi-agent list
+        if agent_list:
+            if self.archive_dir and self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "agents-list.json"
+                dest.write_text(json.dumps(agent_list, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("agent-config", "openclaw.json agents.list", "archive/agents-list.json",
+                        "archived", f"Multi-agent setup ({len(agent_list)} agents) archived for manual recreation")
+
+        # Archive bindings
+        bindings = config.get("bindings") or []
+        if bindings:
+            if self.archive_dir and self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "bindings.json"
+                dest.write_text(json.dumps(bindings, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("agent-config", "openclaw.json bindings", "archive/bindings.json",
+                        "archived", f"Agent routing bindings ({len(bindings)} rules) archived")
+
+    # ── Gateway config ────────────────────────────────────────
+    def migrate_gateway_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        gateway = config.get("gateway") or {}
+        if not gateway:
+            self.record("gateway-config", None, None, "skipped", "No gateway configuration found")
+            return
+
+        # Archive the full gateway config (complex, many settings)
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "gateway-config.json"
+            dest.write_text(json.dumps(gateway, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        self.record("gateway-config", "openclaw.json gateway.*", "archive/gateway-config.json",
+                    "archived", "Gateway config archived. Use 'hermes gateway' to configure.")
+
+        # Extract gateway auth token to .env if present
+        auth = gateway.get("auth") or {}
+        if auth.get("token") and self.migrate_secrets:
+            self._set_env_var("HERMES_GATEWAY_TOKEN", auth["token"], "gateway.auth.token")
+
+    # ── Session config ────────────────────────────────────────
+    def migrate_session_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        session = config.get("session") or {}
+        if not session:
+            self.record("session-config", None, None, "skipped", "No session configuration found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        sr = hermes_cfg.get("session_reset") or {}
+        changes = False
+
+        # OpenClaw uses session.reset (structured) and session.resetTriggers (string array)
+        reset = session.get("reset") or {}
+        reset_triggers = session.get("resetTriggers") or session.get("reset_triggers") or []
+
+        if reset:
+            # Structured reset config: has mode, atHour, idleMinutes
+            mode = reset.get("mode", "")
+            if mode == "daily":
+                sr["mode"] = "daily"
+            elif mode == "idle":
+                sr["mode"] = "idle"
+            else:
+                sr["mode"] = mode or "none"
+            if reset.get("atHour") is not None:
+                sr["at_hour"] = reset["atHour"]
+            if reset.get("idleMinutes"):
+                sr["idle_minutes"] = reset["idleMinutes"]
+            changes = True
+        elif isinstance(reset_triggers, list) and reset_triggers:
+            # Simple string triggers: ["daily", "idle"]
+            has_daily = "daily" in reset_triggers
+            has_idle = "idle" in reset_triggers
+            if has_daily and has_idle:
+                sr["mode"] = "both"
+            elif has_daily:
+                sr["mode"] = "daily"
+            elif has_idle:
+                sr["mode"] = "idle"
+            changes = True
+
+        if changes:
+            hermes_cfg["session_reset"] = sr
+            if self.execute:
+                self.maybe_backup(hermes_cfg_path)
+                dump_yaml_file(hermes_cfg_path, hermes_cfg)
+            self.record("session-config", "openclaw.json session.resetTriggers",
+                        "config.yaml session_reset", "migrated")
+
+        # Archive full session config (identity links, thread bindings, etc.)
+        complex_keys = {"identityLinks", "threadBindings", "maintenance", "scope", "sendPolicy"}
+        complex_session = {k: v for k, v in session.items() if k in complex_keys and v}
+        if complex_session and self.archive_dir:
+            if self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "session-config.json"
+                dest.write_text(json.dumps(complex_session, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("session-config", "openclaw.json session (advanced)",
+                        "archive/session-config.json", "archived",
+                        "Advanced session settings archived (identity links, thread bindings, etc.)")
+
+    # ── Full model providers ──────────────────────────────────
+    def migrate_full_providers(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        models = config.get("models") or {}
+        providers = models.get("providers") or {}
+        if not providers:
+            self.record("full-providers", None, None, "skipped", "No model providers found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        custom_providers = hermes_cfg.get("custom_providers") or []
+        added = 0
+
+        # Well-known providers: just extract API keys
+        WELL_KNOWN = {"openrouter", "openai", "anthropic", "deepseek", "google", "groq"}
+
+        for prov_name, prov_cfg in providers.items():
+            if not isinstance(prov_cfg, dict):
+                continue
+
+            # Extract API key to .env
+            api_key = prov_cfg.get("apiKey") or prov_cfg.get("api_key")
+            if api_key and self.migrate_secrets:
+                env_key = f"{prov_name.upper().replace('-', '_')}_API_KEY"
+                self._set_env_var(env_key, api_key, f"models.providers.{prov_name}.apiKey")
+
+            # For non-well-known providers, create custom_providers entry
+            if prov_name.lower() not in WELL_KNOWN and prov_cfg.get("baseUrl"):
+                # Check if already exists
+                existing_names = {p.get("name", "").lower() for p in custom_providers}
+                if prov_name.lower() in existing_names and not self.overwrite:
+                    self.record("full-providers", f"models.providers.{prov_name}",
+                                "config.yaml custom_providers", "conflict",
+                                f"Provider '{prov_name}' already exists")
+                    continue
+
+                api_type = prov_cfg.get("apiType") or prov_cfg.get("api") or prov_cfg.get("type") or "openai"
+                api_mode_map = {
+                    "openai": "chat_completions",
+                    "openai-completions": "chat_completions",
+                    "openai-responses": "chat_completions",
+                    "anthropic": "anthropic_messages",
+                    "anthropic-messages": "anthropic_messages",
+                    "google-generative-ai": "chat_completions",
+                    "cohere": "chat_completions",
+                }
+                entry = {
+                    "name": prov_name,
+                    "base_url": prov_cfg["baseUrl"],
+                    "api_key": "",  # referenced from .env
+                    "api_mode": api_mode_map.get(api_type, "chat_completions"),
+                }
+                custom_providers.append(entry)
+                added += 1
+                self.record("full-providers", f"models.providers.{prov_name}",
+                            f"config.yaml custom_providers[{prov_name}]", "migrated")
+
+        if added > 0 and self.execute:
+            self.maybe_backup(hermes_cfg_path)
+            hermes_cfg["custom_providers"] = custom_providers
+            dump_yaml_file(hermes_cfg_path, hermes_cfg)
+
+        # Archive model aliases/catalog
+        agent_defaults = (config.get("agents") or {}).get("defaults") or {}
+        model_aliases = agent_defaults.get("models") or {}
+        if model_aliases:
+            if self.archive_dir and self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "model-aliases.json"
+                dest.write_text(json.dumps(model_aliases, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("full-providers", "agents.defaults.models", "archive/model-aliases.json",
+                        "archived", f"Model aliases/catalog ({len(model_aliases)} entries) archived")
+
+    # ── Deep channel config ───────────────────────────────────
+    def migrate_deep_channels(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        channels = config.get("channels") or {}
+        if not channels:
+            self.record("deep-channels", None, None, "skipped", "No channel configuration found")
+            return
+
+        # Extended channel token/allowlist mapping
+        CHANNEL_ENV_MAP = {
+            "matrix": {"token": "MATRIX...OKEN", "tokenField": "accessToken", "allowFrom": "MATRIX_ALLOWED_USERS",
+                        "extras": {"homeserverUrl": "MATRIX_HOMESERVER_URL", "userId": "MATRIX_USER_ID"}},
+            "mattermost": {"token": "MATTERMOST_BOT_TOKEN", "allowFrom": "MATTERMOST_ALLOWED_USERS",
+                           "extras": {"url": "MATTERMOST_URL", "teamId": "MATTERMOST_TEAM_ID"}},
+            "irc": {"extras": {"server": "IRC_SERVER", "nick": "IRC_NICK", "channels": "IRC_CHANNELS"}},
+            "googlechat": {"extras": {"serviceAccountKeyPath": "GOOGLE_CHAT_SA_KEY_PATH"}},
+            "imessage": {},
+            "bluebubbles": {"extras": {"server": "BLUEBUBBLES_SERVER", "password": "BLUEBUBBLES_PASSWORD"}},
+            "msteams": {"token": "MSTEAMS_BOT_TOKEN", "allowFrom": "MSTEAMS_ALLOWED_USERS"},
+            "nostr": {"extras": {"nsec": "NOSTR_NSEC", "relays": "NOSTR_RELAYS"}},
+            "twitch": {"token": "TWITCH_BOT_TOKEN", "extras": {"channels": "TWITCH_CHANNELS"}},
+        }
+
+        for ch_name, ch_mapping in CHANNEL_ENV_MAP.items():
+            ch_cfg = channels.get(ch_name) or {}
+            if not ch_cfg:
+                continue
+
+            # Extract tokens (check flat path, then accounts.default)
+            token_field = ch_mapping.get("tokenField", "botToken")
+            bot_token = self._get_channel_field(ch_cfg, token_field)
+            if ch_mapping.get("token") and bot_token and self.migrate_secrets:
+                self._set_env_var(ch_mapping["token"], str(bot_token),
+                                  f"channels.{ch_name}.{token_field}")
+            allow_val = self._get_channel_field(ch_cfg, "allowFrom")
+            if ch_mapping.get("allowFrom") and allow_val:
+                if isinstance(allow_val, list):
+                    allow_val = ",".join(str(x) for x in allow_val)
+                self._set_env_var(ch_mapping["allowFrom"], str(allow_val),
+                                  f"channels.{ch_name}.allowFrom")
+            # Extra fields
+            for oc_key, env_key in (ch_mapping.get("extras") or {}).items():
+                val = self._get_channel_field(ch_cfg, oc_key)
+                if val:
+                    if isinstance(val, list):
+                        val = ",".join(str(x) for x in val)
+                    is_secret = "password" in oc_key.lower() or "token" in oc_key.lower() or "nsec" in oc_key.lower()
+                    if is_secret and not self.migrate_secrets:
+                        continue
+                    self._set_env_var(env_key, str(val), f"channels.{ch_name}.{oc_key}")
+
+        # Map Discord-specific settings to Hermes config
+        discord_cfg = channels.get("discord") or {}
+        if discord_cfg:
+            hermes_cfg_path = self.target_root / "config.yaml"
+            hermes_cfg = load_yaml_file(hermes_cfg_path)
+            discord_hermes = hermes_cfg.get("discord") or {}
+            changed = False
+            if "requireMention" in discord_cfg:
+                discord_hermes["require_mention"] = discord_cfg["requireMention"]
+                changed = True
+            if discord_cfg.get("autoThread") is not None:
+                discord_hermes["auto_thread"] = discord_cfg["autoThread"]
+                changed = True
+            if changed and self.execute:
+                hermes_cfg["discord"] = discord_hermes
+                dump_yaml_file(hermes_cfg_path, hermes_cfg)
+
+        # Archive complex channel configs (group settings, thread bindings, etc.)
+        complex_archive = {}
+        for ch_name, ch_cfg in channels.items():
+            if not isinstance(ch_cfg, dict):
+                continue
+            complex_keys = {k: v for k, v in ch_cfg.items()
+                          if k not in ("botToken", "appToken", "allowFrom", "enabled")
+                          and v and k not in ("requireMention", "autoThread")}
+            if complex_keys:
+                complex_archive[ch_name] = complex_keys
+
+        if complex_archive and self.archive_dir:
+            if self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "channels-deep-config.json"
+                dest.write_text(json.dumps(complex_archive, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("deep-channels", "openclaw.json channels (advanced settings)",
+                        "archive/channels-deep-config.json", "archived",
+                        f"Deep channel config for {len(complex_archive)} channels archived")
+
+    # ── Browser config ────────────────────────────────────────
+    def migrate_browser_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        browser = config.get("browser") or {}
+        if not browser:
+            self.record("browser-config", None, None, "skipped", "No browser configuration found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        browser_hermes = hermes_cfg.get("browser") or {}
+        changed = False
+
+        # Map fields that have Hermes equivalents
+        if browser.get("cdpUrl"):
+            browser_hermes["cdp_url"] = browser["cdpUrl"]
+            changed = True
+        if browser.get("headless") is not None:
+            browser_hermes["headless"] = browser["headless"]
+            changed = True
+
+        if changed:
+            hermes_cfg["browser"] = browser_hermes
+            if self.execute:
+                self.maybe_backup(hermes_cfg_path)
+                dump_yaml_file(hermes_cfg_path, hermes_cfg)
+            self.record("browser-config", "openclaw.json browser.*", "config.yaml browser",
+                        "migrated")
+
+        # Archive remaining browser settings
+        advanced = {k: v for k, v in browser.items()
+                   if k not in ("cdpUrl", "headless") and v}
+        if advanced and self.archive_dir:
+            if self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "browser-config.json"
+                dest.write_text(json.dumps(advanced, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("browser-config", "openclaw.json browser (advanced)",
+                        "archive/browser-config.json", "archived")
+
+    # ── Tools config ──────────────────────────────────────────
+    def migrate_tools_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        tools = config.get("tools") or {}
+        if not tools:
+            self.record("tools-config", None, None, "skipped", "No tools configuration found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+        changed = False
+
+        # Map exec timeout -> terminal timeout (field is timeoutSec in OpenClaw)
+        exec_cfg = tools.get("exec") or {}
+        timeout_val = exec_cfg.get("timeoutSec") or exec_cfg.get("timeout")
+        if timeout_val:
+            terminal_cfg = hermes_cfg.get("terminal") or {}
+            terminal_cfg["timeout"] = timeout_val
+            hermes_cfg["terminal"] = terminal_cfg
+            changed = True
+
+        # Map web search API key (path: tools.web.search.brave.apiKey in OpenClaw)
+        web_cfg = tools.get("web") or tools.get("webSearch") or {}
+        search_cfg = web_cfg.get("search") or web_cfg if not web_cfg.get("search") else web_cfg["search"]
+        brave_cfg = search_cfg.get("brave") or {}
+        brave_key = brave_cfg.get("apiKey") or search_cfg.get("braveApiKey") or web_cfg.get("braveApiKey")
+        if brave_key and isinstance(brave_key, str) and self.migrate_secrets:
+            self._set_env_var("BRAVE_API_KEY", brave_key, "tools.web.search.brave.apiKey")
+
+        if changed and self.execute:
+            self.maybe_backup(hermes_cfg_path)
+            dump_yaml_file(hermes_cfg_path, hermes_cfg)
+            self.record("tools-config", "openclaw.json tools.*", "config.yaml terminal",
+                        "migrated")
+
+        # Archive full tools config
+        if self.archive_dir:
+            if self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "tools-config.json"
+                dest.write_text(json.dumps(tools, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("tools-config", "openclaw.json tools (full)", "archive/tools-config.json",
+                        "archived", "Full tools config archived for reference")
+
+    # ── Approvals config ──────────────────────────────────────
+    def migrate_approvals_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        approvals = config.get("approvals") or {}
+        if not approvals:
+            self.record("approvals-config", None, None, "skipped", "No approvals configuration found")
+            return
+
+        hermes_cfg_path = self.target_root / "config.yaml"
+        hermes_cfg = load_yaml_file(hermes_cfg_path)
+
+        # Map approval mode (nested under approvals.exec.mode in OpenClaw)
+        exec_approvals = approvals.get("exec") or {}
+        mode = (exec_approvals.get("mode") if isinstance(exec_approvals, dict) else None) or approvals.get("mode") or approvals.get("defaultMode")
+        if mode:
+            mode_map = {"auto": "off", "always": "manual", "smart": "smart", "manual": "manual"}
+            hermes_mode = mode_map.get(mode, "manual")
+            hermes_cfg.setdefault("approvals", {})["mode"] = hermes_mode
+            if self.execute:
+                self.maybe_backup(hermes_cfg_path)
+                dump_yaml_file(hermes_cfg_path, hermes_cfg)
+            self.record("approvals-config", "openclaw.json approvals.mode",
+                        "config.yaml approvals.mode", "migrated", f"Mapped '{mode}' -> '{hermes_mode}'")
+
+        # Archive full approvals config
+        if len(approvals) > 1 and self.archive_dir:
+            if self.execute:
+                self.archive_dir.mkdir(parents=True, exist_ok=True)
+                dest = self.archive_dir / "approvals-config.json"
+                dest.write_text(json.dumps(approvals, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            self.record("approvals-config", "openclaw.json approvals (rules)",
+                        "archive/approvals-config.json", "archived")
+
+    # ── Memory backend ────────────────────────────────────────
+    def migrate_memory_backend(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        memory = config.get("memory") or {}
+        if not memory:
+            self.record("memory-backend", None, None, "skipped", "No memory backend configuration found")
+            return
+
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "memory-backend-config.json"
+            dest.write_text(json.dumps(memory, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        self.record("memory-backend", "openclaw.json memory.*", "archive/memory-backend-config.json",
+                    "archived", "Memory backend config (QMD, vector search, citations) archived for manual review")
+
+    # ── Skills config ─────────────────────────────────────────
+    def migrate_skills_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        skills = config.get("skills") or {}
+        entries = skills.get("entries") or {}
+        if not entries and not skills:
+            self.record("skills-config", None, None, "skipped", "No skills registry configuration found")
+            return
+
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "skills-registry-config.json"
+            dest.write_text(json.dumps(skills, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        self.record("skills-config", "openclaw.json skills.*", "archive/skills-registry-config.json",
+                    "archived", f"Skills registry config ({len(entries)} entries) archived")
+
+    # ── UI / Identity ─────────────────────────────────────────
+    def migrate_ui_identity(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        ui = config.get("ui") or {}
+        if not ui:
+            self.record("ui-identity", None, None, "skipped", "No UI/identity configuration found")
+            return
+
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "ui-identity-config.json"
+            dest.write_text(json.dumps(ui, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        self.record("ui-identity", "openclaw.json ui.*", "archive/ui-identity-config.json",
+                    "archived", "UI theme and identity settings archived")
+
+    # ── Logging / Diagnostics ─────────────────────────────────
+    def migrate_logging_config(self, config: Optional[Dict[str, Any]] = None) -> None:
+        config = config or self.load_openclaw_config()
+        logging_cfg = config.get("logging") or {}
+        diagnostics = config.get("diagnostics") or {}
+        combined = {}
+        if logging_cfg:
+            combined["logging"] = logging_cfg
+        if diagnostics:
+            combined["diagnostics"] = diagnostics
+        if not combined:
+            self.record("logging-config", None, None, "skipped", "No logging/diagnostics configuration found")
+            return
+
+        if self.archive_dir and self.execute:
+            self.archive_dir.mkdir(parents=True, exist_ok=True)
+            dest = self.archive_dir / "logging-diagnostics-config.json"
+            dest.write_text(json.dumps(combined, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        self.record("logging-config", "openclaw.json logging/diagnostics",
+                    "archive/logging-diagnostics-config.json", "archived")
+
+    # ── Helper: set env var ───────────────────────────────────
+    def _set_env_var(self, key: str, value: str, source_label: str) -> None:
+        env_path = self.target_root / ".env"
+        if self.execute:
+            env_data = parse_env_file(env_path)
+            if key in env_data and not self.overwrite:
+                self.record("env-var", source_label, f".env {key}", "conflict",
+                            f"Env var {key} already set")
+                return
+            env_data[key] = value
+            save_env_file(env_path, env_data)
+        self.record("env-var", source_label, f".env {key}", "migrated")
+
+    # ── Generate migration notes ──────────────────────────────
+    def generate_migration_notes(self) -> None:
+        if not self.output_dir:
+            return
+        notes = [
+            "# OpenClaw -> Hermes Migration Notes",
+            "",
+            "This document lists items that require manual attention after migration.",
+            "",
+            "## PM2 / External Processes",
+            "",
+            "Your PM2 processes (Discord bots, Telegram bots, etc.) are NOT affected",
+            "by this migration. They run independently and will continue working.",
+            "No action needed for PM2-managed processes.",
+            "",
+        ]
+
+        archived = [i for i in self.items if i.status == "archived"]
+        if archived:
+            notes.extend([
+                "## Archived Items (Manual Review Needed)",
+                "",
+                "These OpenClaw configurations were archived because they don't have a",
+                "direct 1:1 mapping in Hermes. Review each file and recreate manually:",
+                "",
+            ])
+            for item in archived:
+                notes.append(f"- **{item.kind}**: `{item.destination}` -- {item.reason}")
+            notes.append("")
+
+        conflicts = [i for i in self.items if i.status == "conflict"]
+        if conflicts:
+            notes.extend([
+                "## Conflicts (Existing Hermes Config Not Overwritten)",
+                "",
+                "These items already existed in your Hermes config. Re-run with",
+                "`--overwrite` to force, or merge manually:",
+                "",
+            ])
+            for item in conflicts:
+                notes.append(f"- **{item.kind}**: {item.reason}")
+            notes.append("")
+
+        has_cron_config_archive = any(
+            i.kind == "cron-jobs" and i.status == "archived" and i.destination and i.destination.endswith("cron-config.json")
+            for i in self.items
+        )
+        has_cron_store_archive = any(
+            i.kind == "cron-jobs" and i.status == "archived" and i.destination and i.destination.endswith("cron-store")
+            for i in self.items
+        )
+
+        notes.extend([
+            "## IMPORTANT: Archive the OpenClaw Directory",
+            "",
+            "After migration, your OpenClaw directory still exists on disk with workspace",
+            "state files (todo.json, sessions, logs). If the Hermes agent discovers these",
+            "directories, it may read/write to them instead of the Hermes state, causing",
+            "confusion (e.g., cron jobs reading a different todo list than interactive sessions).",
+            "",
+            "**Strongly recommended:** Run `hermes claw cleanup` to rename the OpenClaw",
+            "directory to `.openclaw.pre-migration`. This prevents the agent from finding it.",
+            "The directory is renamed, not deleted — you can undo this at any time.",
+            "",
+            "If you skip this step and notice the agent getting confused about workspaces",
+            "or todo lists, run `hermes claw cleanup` to fix it.",
+            "",
+            "## Hermes-Specific Setup",
+            "",
+            "After migration, you may want to:",
+            "- Run `hermes claw cleanup` to archive the OpenClaw directory (prevents state confusion)",
+            "- Run `hermes setup` to configure any remaining settings",
+            "- Run `hermes mcp list` to verify MCP servers were imported correctly",
+        ])
+
+        if has_cron_config_archive:
+            notes.append("- Run `hermes cron` to recreate scheduled tasks (see archive/cron-config.json)")
+        elif has_cron_store_archive:
+            notes.append("- Run `hermes cron` to recreate scheduled tasks (see archived cron-store)")
+
+        # Check if skills were imported
+        has_skills = any(i.kind == "skills" and i.status == "migrated" for i in self.items)
+        if has_skills:
+            notes.extend([
+                "",
+                "## Imported Skills",
+                "",
+                "Imported skills require a new session to take effect. After migration,",
+                "restart your agent or start a new chat session, then run `/skills`",
+                "to verify they loaded correctly.",
+                "",
+            ])
+
+        # Check if WhatsApp was detected
+        has_whatsapp = any(i.kind == "whatsapp-settings" and i.status == "migrated" for i in self.items)
+        if has_whatsapp:
+            notes.extend([
+                "",
+                "## WhatsApp Requires Re-Pairing",
+                "",
+                "WhatsApp uses QR-code pairing, not token-based auth. Your allowlist",
+                "was migrated, but you must re-pair the device by running:",
+                "",
+                "    hermes whatsapp",
+                "",
+            ])
+
+        notes.extend([
+            "- Run `hermes gateway install` if you need the gateway service",
+            "- Review `~/.hermes/config.yaml` for any adjustments",
+            "",
+        ])
+
+        if self.execute:
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+            (self.output_dir / "MIGRATION_NOTES.md").write_text(
+                "\n".join(notes) + "\n", encoding="utf-8"
+            )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Migrate OpenClaw user state into Hermes Agent.")
+    parser.add_argument("--source", default=str(Path.home() / ".openclaw"), help="OpenClaw home directory")
+    parser.add_argument("--target", default=os.environ.get("HERMES_HOME") or str(Path.home() / ".hermes"), help="Hermes home directory")
+    parser.add_argument(
+        "--workspace-target",
+        help="Optional workspace root where the workspace instructions file should be copied",
+    )
+    parser.add_argument("--execute", action="store_true", help="Apply changes instead of reporting a dry run")
+    parser.add_argument("--overwrite", action="store_true", help="Overwrite existing Hermes targets after backing them up")
+    parser.add_argument(
+        "--migrate-secrets",
+        action="store_true",
+        help="Import a narrow allowlist of Hermes-compatible secrets into the target env file",
+    )
+    parser.add_argument(
+        "--skill-conflict",
+        choices=sorted(SKILL_CONFLICT_MODES),
+        default="skip",
+        help="How to handle imported skill directory conflicts: skip, overwrite, or rename the imported copy.",
+    )
+    parser.add_argument(
+        "--preset",
+        choices=sorted(MIGRATION_PRESETS),
+        help="Apply a named migration preset. 'user-data' excludes allowlisted secrets; 'full' includes all compatible groups.",
+    )
+    parser.add_argument(
+        "--include",
+        action="append",
+        default=[],
+        help="Comma-separated migration option ids to include (default: all). "
+             f"Valid ids: {', '.join(sorted(MIGRATION_OPTION_METADATA))}",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        help="Comma-separated migration option ids to skip. "
+             f"Valid ids: {', '.join(sorted(MIGRATION_OPTION_METADATA))}",
+    )
+    parser.add_argument("--output-dir", help="Where to write report, backups, and archived docs")
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_output",
+        help="Print the migration report as JSON on stdout (redacted). "
+             "Combine with no --execute for a safe plan-only machine-readable preview.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        selected_options = resolve_selected_options(args.include, args.exclude, preset=args.preset)
+    except ValueError as exc:
+        print(json.dumps({"error": str(exc)}, indent=2, ensure_ascii=False))
+        return 2
+    migrator = Migrator(
+        source_root=Path(os.path.expanduser(args.source)).resolve(),
+        target_root=Path(os.path.expanduser(args.target)).resolve(),
+        execute=bool(args.execute),
+        workspace_target=Path(os.path.expanduser(args.workspace_target)).resolve() if args.workspace_target else None,
+        overwrite=bool(args.overwrite),
+        migrate_secrets=bool(args.migrate_secrets),
+        output_dir=Path(os.path.expanduser(args.output_dir)).resolve() if args.output_dir else None,
+        selected_options=selected_options,
+        preset_name=args.preset or "",
+        skill_conflict_mode=args.skill_conflict,
+    )
+    report = migrator.migrate()
+
+    # ── Machine-readable JSON mode ────────────────────────────
+    # When --json is set, print the redacted report to stdout and skip the
+    # human-readable terminal recap.  Useful for CI and scripted wrappers.
+    if getattr(args, "json_output", False):
+        print(json.dumps(redact_migration_value(report), indent=2, ensure_ascii=False))
+        return 0
+
+    # ── Human-readable terminal recap ─────────────────────────
+    s = report["summary"]
+    items = report["items"]
+    mode_label = "DRY RUN" if not args.execute else "EXECUTED"
+    total = sum(s.values())
+
+    print()
+    print(f"  ╔══════════════════════════════════════════════════════╗")
+    print(f"  ║   OpenClaw -> Hermes Migration   [{mode_label:>8s}]   ║")
+    print(f"  ╠══════════════════════════════════════════════════════╣")
+    print(f"  ║  Source:  {str(report['source_root'])[:42]:<42s}  ║")
+    print(f"  ║  Target:  {str(report['target_root'])[:42]:<42s}  ║")
+    print(f"  ╠══════════════════════════════════════════════════════╣")
+    print(f"  ║  ✔ Migrated:  {s.get('migrated', 0):>3d}    ◆ Archived:  {s.get('archived', 0):>3d}        ║")
+    print(f"  ║  ⊘ Skipped:   {s.get('skipped', 0):>3d}    ⚠ Conflicts: {s.get('conflict', 0):>3d}        ║")
+    print(f"  ║  ✖ Errors:    {s.get('error', 0):>3d}    Total:       {total:>3d}        ║")
+    print(f"  ╚══════════════════════════════════════════════════════╝")
+
+    # Show what was migrated
+    migrated = [i for i in items if i["status"] == "migrated"]
+    if migrated:
+        print()
+        print("  Migrated:")
+        seen_kinds = set()
+        for item in migrated:
+            label = item["kind"]
+            if label in seen_kinds:
+                continue
+            seen_kinds.add(label)
+            dest = item.get("destination") or ""
+            if dest.startswith(str(report["target_root"])):
+                dest = "~/.hermes/" + dest[len(str(report["target_root"])) + 1:]
+            meta = MIGRATION_OPTION_METADATA.get(label, {})
+            display = meta.get("label", label)
+            print(f"    ✔ {display:<35s} -> {dest}")
+
+    # Show what was archived
+    archived = [i for i in items if i["status"] == "archived"]
+    if archived:
+        print()
+        print("  Archived (manual review needed):")
+        seen_kinds = set()
+        for item in archived:
+            label = item["kind"]
+            if label in seen_kinds:
+                continue
+            seen_kinds.add(label)
+            reason = item.get("reason", "")
+            meta = MIGRATION_OPTION_METADATA.get(label, {})
+            display = meta.get("label", label)
+            short_reason = reason[:50] + "..." if len(reason) > 50 else reason
+            print(f"    ◆ {display:<35s}  {short_reason}")
+
+    # Show conflicts
+    conflicts = [i for i in items if i["status"] == "conflict"]
+    if conflicts:
+        print()
+        print("  Conflicts (use --overwrite to force):")
+        for item in conflicts:
+            print(f"    ⚠ {item['kind']}: {item.get('reason', '')}")
+
+    # Show errors
+    errors = [i for i in items if i["status"] == "error"]
+    if errors:
+        print()
+        print("  Errors:")
+        for item in errors:
+            print(f"    ✖ {item['kind']}: {item.get('reason', '')}")
+
+    # PM2 reassurance
+    print()
+    print("  ℹ PM2 processes (Discord/Telegram bots) are NOT affected.")
+
+    # Next steps
+    if args.execute:
+        print()
+        print("  Next steps:")
+        print("    1. Review ~/.hermes/config.yaml")
+        print("    2. Run: hermes mcp list")
+        if any(i["kind"] == "cron-jobs" and i["status"] == "archived" for i in items):
+            print("    3. Recreate cron jobs: hermes cron")
+        if report.get("output_dir"):
+            print(f"    → Full report: {report['output_dir']}/MIGRATION_NOTES.md")
+    elif not args.execute:
+        print()
+        print("  This was a dry run. Add --execute to apply changes.")
+
+    print()
+
+    # Also dump JSON for programmatic use
+    if os.environ.get("MIGRATION_JSON_OUTPUT"):
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+
+    return 0 if s.get("error", 0) == 0 else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())