From 999770b75cc8076d131bfd9e42295fad54f1e21a Mon Sep 17 00:00:00 2001
From: admin <admin@rommark.dev>
Date: Tue, 5 May 2026 18:22:52 +0000
Subject: [PATCH] docs: self-evolution section + feature comparison table

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 53 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9a20b160..a50cdbc7 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,49 @@ User sends voice message
 - **Offline** — zero network calls, zero API costs
 - **Good enough** — ~95% accuracy for English speech
 
+### 🧬 Self-Evolution
+
+zCode can **modify its own source code** — and survive the attempt. Every change goes through a safety chain that guarantees rollback on any failure.
+
+**Safety chain (8 steps):**
+```
+AI requests patch
+       │
+       ▼
+┌──────────────────┐
+│ 1. Git stash     │  ← save uncommitted work
+│ 2. Git commit    │  ← checkpoint current state
+│ 3. File backup   │  ← copy original to .self-evolve-backups/
+│ 4. Apply patch   │  ← string find/replace in target file
+│ 5. Syntax check  │  ← node --check / py_compile / JSON.parse
+│ 6. Git commit    │  ← commit the change
+│ 7. Push + restart│  ← deploy to production
+│ 8. Health + smoke│  ← verify bot is alive and responding
+└──────────────────┘
+       │
+   ┌───┴───┐
+   │ FAIL? │──── auto git reset + restart + restore from backup
+   └───┬───┘
+       │ OK
+       ▼
+   ✅ Live
+```
+
+**Protected files** — the bot **cannot** modify these (would brick itself):
+- `SelfEvolveTool.js` — the safety system itself
+- `stt.py` — voice recognition bridge
+
+**Backup system:**
+- Every `patch` auto-saves the original file to `.self-evolve-backups/` with a timestamp ID
+- `backups` action lists all backups (file, size, timestamp)
+- `restore` action copies any backup back to production (with its own safety checks)
+- Backups survive git corruption — they're plain file copies, not git objects
+- Restoring also creates a pre-restore backup (undo the undo)
+
+**Actions:** `read`, `patch`, `list_files`, `git_log`, `diff`, `backups`, `restore`
+
+**Rate limit:** 1 patch per 60 seconds (prevents runaway self-modification loops)
+
 ### 🧠 Intelligence Routing
 
 The core of zCode CLI X's reliability. A unified agentic loop that handles both streaming and non-streaming through the same execution path — no more split paths that lose context or hang silently.
@@ -517,11 +560,16 @@ Z.AI API (SSE)
 | Telegram integration | ✅ Native bot + webhook + streaming | ✅ 2-way Telegram bridge | ❌ None |
 | Discord | ✅ Native bot (discord.js) | ✅ Full Discord integration | ❌ None |
 | Multi-channel delivery | ✅ Delivery hub (TG + DC + WS + log) | ✅ Cron→multi-platform | ❌ None |
-| **Voice** | | | |
-| Speech-to-Text | ✅ Vosk (offline, ~200ms, 68MB) | ⚠️ Whisper (needs GPU) | ❌ None |
-| Text-to-Speech | ✅ Edge TTS (free, 100+ voices) | ✅ node-edge-tts | ❌ None |
-| Voice→AI pipeline | ✅ Transcribe → full agentic loop | ⚠️ Separate pipeline | ❌ None |
-| **Infrastructure** | | | |
+|| **Voice** | | | |
+|| Speech-to-Text | ✅ Vosk (offline, ~200ms, 68MB) | ⚠️ Whisper (needs GPU) | ❌ None |
+|| Text-to-Speech | ✅ Edge TTS (free, 100+ voices) | ✅ node-edge-tts | ❌ None |
+|| Voice→AI pipeline | ✅ Transcribe → full agentic loop | ⚠️ Separate pipeline | ❌ None |
+|| **Self-Evolution** | | | |
+|| Self-modifying code | ✅ Patch own source + auto-deploy | ❌ Not supported | ❌ None |
+|| Auto-backup before change | ✅ File-level + git checkpoint | N/A | N/A |
+|| Auto-rollback on failure | ✅ Syntax + health + smoke test | N/A | N/A |
+|| Backup history + restore | ✅ Timestamped backups, 1-command restore | N/A | N/A |
+|| **Infrastructure** | | | |
 | Model routing | ✅ Multi-provider | ✅ Multi-provider routing | ❌ Single model |
 | Context compression | ✅ Compact pipeline | ✅ lean-ctx MCP (90% savings) | ❌ None |
 | Auto-restart | ✅ Process supervisor | ✅ systemd managed | ❌ None |