docs(hooks): tutorial — build a BOOT.md startup checklist (#17202)

Replace the removed built-in boot-md hook (#17093) with a how-to that
shows users how to wire up the same behavior themselves via the hooks
system. Uses _resolve_gateway_model() + _resolve_runtime_agent_kwargs()
so the example works against custom endpoints and OAuth providers,
not just the aggregator defaults that the old built-in silently assumed.

Co-authored-by: teknium1 <teknium@users.noreply.github.com>

website/docs/user-guide/features/hooks.md

@@ -182,6 +182,161 @@ async def handle(event_type: str, context: dict):
         }, timeout=5)
 ```
 
+### Tutorial: BOOT.md — Run a Startup Checklist on Every Gateway Boot
+
+A popular pattern from the community: drop a Markdown checklist at `~/.hermes/BOOT.md`, and have the agent run it once every time the gateway starts. Useful for "on every boot, check overnight cron failures and ping me on Discord if anything failed," or "summarize the last 24h of deploy.log and post it to Slack #ops."
+
+This tutorial shows how to build it yourself as a user-defined hook. Hermes does not ship a built-in BOOT.md hook — you wire up exactly the behavior you want.
+
+#### What we're building
+
+1. A file at `~/.hermes/BOOT.md` with natural-language startup instructions.
+2. A gateway hook that fires on `gateway:startup`, spawns a one-shot agent with your gateway's resolved model/credentials, and runs the BOOT.md instructions.
+3. A `[SILENT]` convention so the agent can opt out of sending a message when there's nothing to report.
+
+#### Step 1: Write your checklist
+
+Create `~/.hermes/BOOT.md`. Write it as if you were giving instructions to a human assistant:
+
+```markdown
+# Startup Checklist
+
+1. Run `hermes cron list` and check if any scheduled jobs failed overnight.
+2. If any failed, send a summary to Discord #ops using the `send_message` tool.
+3. Check if `/opt/app/deploy.log` has any ERROR lines from the last 24 hours. If yes, summarize them and include in the same Discord message.
+4. If nothing went wrong, reply with only `[SILENT]` so no message is sent.
+```
+
+The agent sees this as part of its prompt, so anything you can describe in plain language works — tool calls, shell commands, sending messages, summarizing files.
+
+#### Step 2: Create the hook
+
+```text
+~/.hermes/hooks/boot-md/
+├── HOOK.yaml
+└── handler.py
+```
+
+**`~/.hermes/hooks/boot-md/HOOK.yaml`**
+
+```yaml
+name: boot-md
+description: Run ~/.hermes/BOOT.md on gateway startup
+events:
+  - gateway:startup
+```
+
+**`~/.hermes/hooks/boot-md/handler.py`**
+
+```python
+"""Run ~/.hermes/BOOT.md on every gateway startup."""
+
+import logging
+import threading
+from pathlib import Path
+
+logger = logging.getLogger("hooks.boot-md")
+
+BOOT_FILE = Path.home() / ".hermes" / "BOOT.md"
+
+
+def _build_prompt(content: str) -> str:
+    return (
+        "You are running a startup boot checklist. Follow the instructions "
+        "below exactly.\n\n"
+        "---\n"
+        f"{content}\n"
+        "---\n\n"
+        "Execute each instruction. Use the send_message tool to deliver any "
+        "messages to platforms like Discord or Slack.\n"
+        "If nothing needs attention and there is nothing to report, reply "
+        "with ONLY: [SILENT]"
+    )
+
+
+def _run_boot_agent(content: str) -> None:
+    """Spawn a one-shot agent and execute the checklist.
+
+    Uses the gateway's resolved model and runtime credentials so this works
+    against custom endpoints, aggregators, and OAuth-based providers alike.
+    """
+    try:
+        from gateway.run import _resolve_gateway_model, _resolve_runtime_agent_kwargs
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            model=_resolve_gateway_model(),
+            **_resolve_runtime_agent_kwargs(),
+            platform="gateway",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+            max_iterations=20,
+        )
+        result = agent.run_conversation(_build_prompt(content))
+        response = result.get("final_response", "")
+        if response and "[SILENT]" not in response:
+            logger.info("boot-md completed: %s", response[:200])
+        else:
+            logger.info("boot-md completed (nothing to report)")
+    except Exception as e:
+        logger.error("boot-md agent failed: %s", e)
+
+
+async def handle(event_type: str, context: dict) -> None:
+    if not BOOT_FILE.exists():
+        return
+    content = BOOT_FILE.read_text(encoding="utf-8").strip()
+    if not content:
+        return
+
+    logger.info("Running BOOT.md (%d chars)", len(content))
+
+    # Background thread so gateway startup isn't blocked on a full agent turn.
+    thread = threading.Thread(
+        target=_run_boot_agent,
+        args=(content,),
+        name="boot-md",
+        daemon=True,
+    )
+    thread.start()
+```
+
+The two key lines:
+
+- `_resolve_gateway_model()` reads the gateway's currently-configured model.
+- `_resolve_runtime_agent_kwargs()` resolves provider credentials the same way a normal gateway turn does — including API keys, base URLs, OAuth tokens, and credential pools.
+
+Without these, a bare `AIAgent()` falls back to built-in defaults and will 401 against any non-default endpoint.
+
+#### Step 3: Test it
+
+Restart the gateway:
+
+```bash
+hermes gateway restart
+```
+
+Watch the logs:
+
+```bash
+hermes logs --follow --level INFO | grep boot-md
+```
+
+You should see `Running BOOT.md (N chars)` followed by either `boot-md completed: ...` (summary of what the agent did) or `boot-md completed (nothing to report)` when the agent replied `[SILENT]`.
+
+Delete `~/.hermes/BOOT.md` to disable the checklist — the hook stays loaded but silently skips when the file isn't there.
+
+#### Extending the pattern
+
+- **Schedule-aware checklists:** key off `datetime.now().weekday()` inside BOOT.md's instructions ("if it's Monday, also check the weekly deploy log"). The instructions are free-form text, so anything the agent can reason about is fair game.
+- **Multiple checklists:** point the hook at a different file (`STARTUP.md`, `MORNING.md`, etc.) and register separate hook directories for each.
+- **Non-agent variant:** if you don't need a full agent loop, skip `AIAgent` entirely and have the handler post a fixed notification directly via `httpx`. Cheaper, faster, and has no provider dependency.
+
+#### Why this isn't a built-in
+
+An earlier version of Hermes shipped this as a built-in hook and silently spawned an agent with bare defaults on every gateway boot. That surprised users with custom endpoints and made the feature invisible to users who didn't know it was running. Keeping it as a documented pattern — built by you, in your hooks directory — means you see exactly what it does and opt in by writing the files.
+
 ### How It Works
 
 1. On gateway startup, `HookRegistry.discover_and_load()` scans `~/.hermes/hooks/`