From df8ccc694b9b9b0f42cd2faaa6c54ab2fa034c0b Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Tue, 21 Apr 2026 07:14:44 +0000 Subject: [PATCH] docs: add MIGRATION-PLAYBOOK.md for manual cutover steps Manual sequence Marius runs AFTER the PR merges. Pre-flight (tests, backups), stop-services, ANAF live-state copy, dashboard migration, memory inversion (clawd/memory -> echo-core/memory), systemd, crontab, OpenClaw decommission, verification, and rollback path. Flagged at the top as human-only -- no AI agent should auto-execute these steps. --- MIGRATION-PLAYBOOK.md | 163 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 MIGRATION-PLAYBOOK.md diff --git a/MIGRATION-PLAYBOOK.md b/MIGRATION-PLAYBOOK.md new file mode 100644 index 0000000..38ca948 --- /dev/null +++ b/MIGRATION-PLAYBOOK.md @@ -0,0 +1,163 @@ +# OpenClaw → Echo-Core Migration Playbook + +> **⚠️ This document should NOT be run by an AI agent.** +> Marius runs it by hand, one step at a time, verifying between steps. +> Each step has a "before" and "after" state. Never batch. + +Run this after the PR `feat/openclaw-consolidation-2026-04` has merged to master. +Estimated downtime: 5–10 minutes. Rollback path at the bottom. + +--- + +## Pre-flight (read-only) + +1. Confirm clean git state on echo-core master: + ``` + cd /home/moltbot/echo-core && git status + ``` + +2. Verify tests pass: + ``` + cd /home/moltbot/echo-core + source .venv/bin/activate && pytest tests/ -x + ``` + +3. Backup: + ``` + cp -rp /home/moltbot/clawd/dashboard /home/moltbot/clawd-backup-$(date +%Y-%m-%d)/ + cp -rp /home/moltbot/clawd/memory /home/moltbot/clawd-backup-$(date +%Y-%m-%d)/memory + ``` + +## Legacy consumer grep (decide on compat symlink) + +4. Check whether anything still reads clawd/memory: + ``` + grep -rn 'clawd/memory' /home/moltbot/{bin,.config,.openclaw} 2>/dev/null + grep -rn 'clawd/memory' /home/moltbot/echo-core 2>/dev/null + ``` + - If empty → skip **step 11** (no compat symlink needed). + - If non-empty → keep **step 11**. + +## Stop services + +5. ``` + systemctl --user stop echo-core echo-taskboard echo-whatsapp-bridge openclaw-gateway + ``` + +## Copy ANAF live state + +6. ``` + cp -rp /home/moltbot/clawd/tools/anaf-monitor/{hashes.json,versions.json,monitor.log} \ + /home/moltbot/echo-core/tools/anaf-monitor/ 2>/dev/null + cp -rp /home/moltbot/clawd/tools/anaf-monitor/snapshots \ + /home/moltbot/echo-core/tools/anaf-monitor/ + diff -r /home/moltbot/clawd/tools/anaf-monitor/snapshots \ + /home/moltbot/echo-core/tools/anaf-monitor/snapshots + ``` + Diff should be empty (or only show new snapshots echo-core captured during testing). + +## Dashboard migration + +7. Delete echo-core dashboard placeholder content if any collisions, then: + ``` + cp -rp /home/moltbot/clawd/dashboard/{habits,issues,status,todos}.json \ + /home/moltbot/echo-core/dashboard/ + cp -rp /home/moltbot/clawd/dashboard/tests/ \ + /home/moltbot/echo-core/dashboard/tests/ + # Recreate the 4 dashboard symlinks pointing into echo-core: + ln -sfn /home/moltbot/echo-core/memory /home/moltbot/echo-core/dashboard/memory + ln -sfn /home/moltbot/echo-core/conversations /home/moltbot/echo-core/dashboard/conversations # create conversations/ first if you want this + ln -sfn /home/moltbot/echo-core/memory/kb /home/moltbot/echo-core/dashboard/notes-data + ln -sfn /home/moltbot/echo-core/memory/kb/youtube /home/moltbot/echo-core/dashboard/youtube-notes + ``` + +## Memory inversion + +8. `rm /home/moltbot/echo-core/memory` *(removes symlink only, not target)* +9. `cp -rp /home/moltbot/clawd/memory /home/moltbot/echo-core/memory` +10. `diff -rq /home/moltbot/clawd/memory /home/moltbot/echo-core/memory` *(verify identical)* +11. *(only if step 4 found consumers)* + ``` + mv /home/moltbot/clawd/memory /home/moltbot/clawd/memory.old-2026-04 + ln -s /home/moltbot/echo-core/memory /home/moltbot/clawd/memory + ``` +12. `rm -rf /home/moltbot/echo-core/memory.bak` *(leftover, safe to delete)* + +## Systemd + +13. Copy the template into place: + ``` + cp /home/moltbot/echo-core/dashboard/echo-taskboard.service \ + /home/moltbot/.config/systemd/user/echo-taskboard.service + systemctl --user daemon-reload + ``` + +## Crontab + +14. ``` + bash /home/moltbot/echo-core/scripts/update_crontab.sh + ``` + +## Decommission OpenClaw + +15. `systemctl --user stop openclaw-gateway` +16. `systemctl --user disable openclaw-gateway` +17. Strip credentials from `~/.openclaw/` but keep `jobs.json.bak`: + ``` + cd /home/moltbot/.openclaw + find . -name 'auth*' -o -name '*token*' -o -name '*.secret' | xargs rm -v 2>/dev/null + ls -la agents/*/ # inspect for any remaining secrets, delete manually + ``` +18. **Note:** schedule a reminder for 2026-05-21 to `rm -rf /home/moltbot/.openclaw` + entirely if nothing was restored. + +## Restart + +19. `systemctl --user start echo-core echo-taskboard echo-whatsapp-bridge` +20. `systemctl --user status echo-core echo-taskboard echo-whatsapp-bridge` — all **active (running)**. +21. `systemctl --user status openclaw-gateway` — **inactive (dead)**. + +## Verification + +22. `curl -s http://localhost:8088/api/status` → `{"status":"ok",...}` +23. Visit `https://moltbot.tailf7372d.ts.net/echo/` — home page loads. +24. `/api/cron` panel populated with echo-core jobs (anaf-monitor, morning-report, etc). +25. `/api/agents` returns 404 (removed). +26. Click **Commit** in `index.html` — creates commit on echo-core repo. +27. Manually trigger anaf monitor: + ``` + cd /home/moltbot/echo-core && .venv/bin/python3 tools/anaf-monitor/monitor_v2.py + ``` + Verify `status.json` updates **and** stdout ends with + `GSTACK-CRON: changes=N`. +28. Wait for first scheduled anaf-monitor trigger (10:00 or 16:00 Mon-Fri). + Check `echo-core.log` for execution. + +--- + +## Rollback path (if anything breaks badly) + +``` +systemctl --user stop echo-core echo-taskboard echo-whatsapp-bridge +rm -rf /home/moltbot/echo-core/memory +cp -rp /home/moltbot/clawd-backup-YYYY-MM-DD/memory /home/moltbot/clawd/memory # restore +ln -s /home/moltbot/clawd/memory /home/moltbot/echo-core/memory # restore symlink + +# Restore old systemd unit from git history in clawd repo if available, else rewrite manually. +git -C /home/moltbot/echo-core checkout master # revert to pre-merge state +systemctl --user daemon-reload +systemctl --user start echo-core echo-taskboard echo-whatsapp-bridge +systemctl --user start openclaw-gateway # if wanted +``` + +--- + +## Notes + +- **Cron schedules are Bucharest local time**, not UTC. +- **Most imported claude jobs arrive DISABLED** — enable them via `eco` / dashboard + once you've verified each one produces the expected output. +- `heartbeat-2h` is the **only imported claude job that stays enabled** (preserving + its state from OpenClaw). +- The 5 shell jobs (anaf-monitor, security-audit-daily, kb-index-refresh, + archive-tasks-daily, backup-config) start **enabled** on day one.