feat(hooks): run boot.md on gateway startup

docs/cli/hooks.md

@@ -7,7 +7,7 @@ read_when:
 
 # `clawdbot hooks`
 
-Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, etc.).
+Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, and gateway startup).
 
 Related:
 - Hooks: [Hooks](/hooks)
@@ -29,9 +29,10 @@ List all discovered hooks from workspace, managed, and bundled directories.
 **Example output:**
 
 ```
-Hooks (3/3 ready)
+Hooks (4/4 ready)
 
 Ready:
+  🚀 boot-md ✓ - Run BOOT.md on gateway startup
   📝 command-logger ✓ - Log all command events to a centralized audit file
   💾 session-memory ✓ - Save session context to memory when /new command is issued
   😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
@@ -107,8 +108,8 @@ Show summary of hook eligibility status (how many are ready vs. not ready).
 ```
 Hooks Status
 
-Total hooks: 2
-Ready: 2
+Total hooks: 4
+Ready: 4
 Not ready: 0
 ```
 
@@ -273,3 +274,17 @@ clawdbot hooks enable soul-evil
 ```
 
 **See:** [SOUL Evil Hook](/hooks/soul-evil)
+
+### boot-md
+
+Runs `BOOT.md` when the gateway starts (after channels start).
+
+**Events**: `gateway:startup`
+
+**Enable**:
+
+```bash
+clawdbot hooks enable boot-md
+```
+
+**See:** [boot-md documentation](/hooks#boot-md)

docs/concepts/agent-workspace.md

@@ -86,6 +86,10 @@ These are the standard files Clawdbot expects inside the workspace:
   - Optional tiny checklist for heartbeat runs.
   - Keep it short to avoid token burn.
 
+- `BOOT.md`
+  - Optional startup checklist executed on gateway restart when internal hooks are enabled.
+  - Keep it short; use the message tool for outbound sends.
+
 - `BOOTSTRAP.md`
   - One-time first-run ritual.
   - Only created for a brand-new workspace.

docs/docs.json

@@ -657,6 +657,10 @@
       "source": "/templates/AGENTS",
       "destination": "/reference/templates/AGENTS"
     },
+    {
+      "source": "/templates/BOOT",
+      "destination": "/reference/templates/BOOT"
+    },
     {
       "source": "/templates/BOOTSTRAP",
       "destination": "/reference/templates/BOOTSTRAP"
@@ -1051,6 +1055,7 @@
           "reference/RELEASING",
           "reference/AGENTS.default",
           "reference/templates/AGENTS",
+          "reference/templates/BOOT",
           "reference/templates/BOOTSTRAP",
           "reference/templates/HEARTBEAT",
           "reference/templates/IDENTITY",

docs/hooks.md

@@ -37,10 +37,11 @@ The hooks system allows you to:
 
 ### Bundled Hooks
 
-Clawdbot ships with three bundled hooks that are automatically discovered:
+Clawdbot ships with four bundled hooks that are automatically discovered:
 
 - **💾 session-memory**: Saves session context to your agent workspace (default `~/clawd/memory/`) when you issue `/new`
 - **📝 command-logger**: Logs all command events to `~/.clawdbot/logs/commands.log`
+- **🚀 boot-md**: Runs `BOOT.md` when the gateway starts (requires internal hooks enabled)
 - **😈 soul-evil**: Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance
 
 List available hooks:
@@ -195,7 +196,7 @@ Each event includes:
 
 ```typescript
 {
-  type: 'command' | 'session' | 'agent',
+  type: 'command' | 'session' | 'agent' | 'gateway',
   action: string,              // e.g., 'new', 'reset', 'stop'
   sessionKey: string,          // Session identifier
   timestamp: Date,             // When the event occurred
@@ -228,6 +229,12 @@ Triggered when agent commands are issued:
 
 - **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)
 
+### Gateway Events
+
+Triggered when the gateway starts:
+
+- **`gateway:startup`**: After channels start and hooks are loaded
+
 ### Future Events
 
 Planned event types:
@@ -542,6 +549,26 @@ clawdbot hooks enable soul-evil
 }
 ```
 
+### boot-md
+
+Runs `BOOT.md` when the gateway starts (after channels start).
+Internal hooks must be enabled for this to run.
+
+**Events**: `gateway:startup`
+
+**Requirements**: `workspace.dir` must be configured
+
+**What it does**:
+1. Reads `BOOT.md` from your workspace
+2. Runs the instructions via the agent runner
+3. Sends any requested outbound messages via the message tool
+
+**Enable**:
+
+```bash
+clawdbot hooks enable boot-md
+```
+
 ## Best Practices
 
 ### Keep Handlers Fast
@@ -614,6 +641,7 @@ The gateway logs hook loading at startup:
 ```
 Registered hook: session-memory -> command:new
 Registered hook: command-logger -> command
+Registered hook: boot-md -> gateway:startup
 ```
 
 ### Check Discovery

docs/reference/templates/BOOT.md

@@ -0,0 +1,9 @@
+---
+summary: "Workspace template for BOOT.md"
+read_when:
+  - Adding a BOOT.md checklist
+---
+# BOOT.md
+
+Add short, explicit instructions for what Clawdbot should do on startup (enable `hooks.internal.enabled`).
+If the task sends a message, use the message tool and then reply with NO_REPLY.