diff --git a/README.md b/README.md
index bfc65ccfe..770e15d4c 100644
--- a/README.md
+++ b/README.md
@@ -1008,7 +1008,7 @@ This keeps the runtime lightweight while making new OpenAI-compatible backends m
 PicoClaw provides typed lifecycle hooks for observability, outbound filtering, and tool guardrails.
 
 - Register hooks in Go at startup with `hooks.NewHookRegistry()`.
-- Attach once via `agentLoop.SetHooks(registry)` before `Run()`.
+- Attach once via `agentLoop.SetHooks(registry)` before `Run()` and handle setup errors.
 - If hooks are not set, default behavior is unchanged.
 
 See runnable examples: [docs/hooks-plugin-examples.md](docs/hooks-plugin-examples.md)
diff --git a/docs/hooks-plugin-examples.md b/docs/hooks-plugin-examples.md
index af7e500a2..d78b5a1cb 100644
--- a/docs/hooks-plugin-examples.md
+++ b/docs/hooks-plugin-examples.md
@@ -15,7 +15,7 @@ PicoClaw's plugin model is a startup-time hook registry:
 
 1. Build a registry (`hooks.NewHookRegistry()`).
 2. Register one or more handlers per lifecycle hook with priority.
-3. Attach once with `agentLoop.SetHooks(registry)` before `agentLoop.Run(...)`.
+3. Attach once with `agentLoop.SetHooks(registry)` before `agentLoop.Run(...)` (check error).
 4. Agent loop triggers hook handlers at specific lifecycle points.
 
 Execution semantics:
@@ -114,7 +114,9 @@ Attach once during startup:
 
 ```go
 agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
-agentLoop.SetHooks(buildHooks()) // Must be called before Run()
+if err := agentLoop.SetHooks(buildHooks()); err != nil {
+	panic(err) // replace with your startup error handling
+}
 ```
 
 ## Priority and Cancellation