From b8a82923e9a86a6a7a2f5cdc0bb69525d479ee44 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sun, 18 Jan 2026 06:21:00 +0000
Subject: [PATCH] docs: add soul-evil hook docs

---
 docs/cli/hooks.md                   |  2 +-
 docs/docs.json                      |  2 +
 docs/hooks.md                       |  2 +
 docs/hooks/soul-evil.md             | 66 +++++++++++++++++++++++++++++
 src/hooks/bundled/README.md         |  1 +
 src/hooks/bundled/soul-evil/HOOK.md |  2 +-
 6 files changed, 73 insertions(+), 2 deletions(-)
 create mode 100644 docs/hooks/soul-evil.md

diff --git a/docs/cli/hooks.md b/docs/cli/hooks.md
index 04538b3a7..88684feb6 100644
--- a/docs/cli/hooks.md
+++ b/docs/cli/hooks.md
@@ -271,4 +271,4 @@ Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by
 clawdbot hooks enable soul-evil
 ```
 
-**See:** [soul-evil documentation](/hooks#soul-evil)
+**See:** [SOUL Evil Hook](/hooks/soul-evil)
diff --git a/docs/docs.json b/docs/docs.json
index 7d627fd69..b7ac1375b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -956,6 +956,8 @@
       {
         "group": "Automation & Hooks",
         "pages": [
+          "hooks",
+          "hooks/soul-evil",
           "automation/auth-monitoring",
           "automation/webhook",
           "automation/gmail-pubsub",
diff --git a/docs/hooks.md b/docs/hooks.md
index 26047b3c0..8d99327f4 100644
--- a/docs/hooks.md
+++ b/docs/hooks.md
@@ -511,6 +511,8 @@ Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by
 
 **Events**: `agent:bootstrap`
 
+**Docs**: [SOUL Evil Hook](/hooks/soul-evil)
+
 **Output**: No files written; swaps happen in-memory only.
 
 **Enable**:
diff --git a/docs/hooks/soul-evil.md b/docs/hooks/soul-evil.md
new file mode 100644
index 000000000..6f9278c6c
--- /dev/null
+++ b/docs/hooks/soul-evil.md
@@ -0,0 +1,66 @@
+---
+summary: "SOUL Evil hook (swap SOUL.md with SOUL_EVIL.md)"
+read_when:
+  - You want to enable or tune the SOUL Evil hook
+  - You want a purge window or random-chance persona swap
+---
+
+# SOUL Evil Hook
+
+The SOUL Evil hook swaps the **injected** `SOUL.md` content with `SOUL_EVIL.md` during
+a purge window or by random chance. It does **not** modify files on disk.
+
+## How It Works
+
+When `agent:bootstrap` runs, the hook can replace the `SOUL.md` content in memory
+before the system prompt is assembled. If `SOUL_EVIL.md` is missing or empty,
+Clawdbot logs a warning and keeps the normal `SOUL.md`.
+
+Sub-agent runs do **not** include `SOUL.md` in their bootstrap files, so this hook
+has no effect on sub-agents.
+
+## Enable
+
+```bash
+clawdbot hooks enable soul-evil
+```
+
+Then set the config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "soul-evil": {
+          "enabled": true,
+          "file": "SOUL_EVIL.md",
+          "chance": 0.1,
+          "purge": { "at": "21:00", "duration": "15m" }
+        }
+      }
+    }
+  }
+}
+```
+
+## Options
+
+- `file` (string): alternate SOUL filename (default: `SOUL_EVIL.md`)
+- `chance` (number 0–1): random chance per run to use `SOUL_EVIL.md`
+- `purge.at` (HH:mm): daily purge start (24-hour clock)
+- `purge.duration` (duration): window length (e.g. `30s`, `10m`, `1h`)
+
+**Precedence:** purge window wins over chance.
+
+**Timezone:** uses `agents.defaults.userTimezone` when set; otherwise host timezone.
+
+## Notes
+
+- No files are written or modified on disk.
+- If `SOUL.md` is not in the bootstrap list, the hook does nothing.
+
+## See Also
+
+- [Hooks](/hooks)
diff --git a/src/hooks/bundled/README.md b/src/hooks/bundled/README.md
index be1d64ab1..281cfd1bc 100644
--- a/src/hooks/bundled/README.md
+++ b/src/hooks/bundled/README.md
@@ -39,6 +39,7 @@ Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by
 **Events**: `agent:bootstrap`
 **What it does**: Overrides the injected SOUL content before the system prompt is built.
 **Output**: No files written; swaps happen in-memory only.
+**Docs**: https://docs.clawd.bot/hooks/soul-evil
 
 **Enable**:
 
diff --git a/src/hooks/bundled/soul-evil/HOOK.md b/src/hooks/bundled/soul-evil/HOOK.md
index 88e566c78..776163bd0 100644
--- a/src/hooks/bundled/soul-evil/HOOK.md
+++ b/src/hooks/bundled/soul-evil/HOOK.md
@@ -1,7 +1,7 @@
 ---
 name: soul-evil
 description: "Swap SOUL.md with SOUL_EVIL.md during a purge window or by random chance"
-homepage: https://docs.clawd.bot/hooks#soul-evil
+homepage: https://docs.clawd.bot/hooks/soul-evil
 metadata:
   {
     "clawdbot":