add some documentation for blue book

docs/runner/hero.md

@@ -0,0 +1,71 @@
+# Hero Runner
+
+Executes heroscripts using the Hero CLI tool.
+
+## Overview
+
+The Hero runner pipes job payloads directly to `hero run -s` via stdin, making it ideal for executing Hero automation tasks and heroscripts.
+
+## Features
+
+- **Heroscript Execution**: Direct stdin piping to `hero run -s`
+- **No Temp Files**: Secure execution without filesystem artifacts
+- **Environment Variables**: Full environment variable support
+- **Timeout Support**: Respects job timeout settings
+- **Signature Verification**: Cryptographic job verification
+
+## Usage
+
+```bash
+# Start the runner
+herorunner my-hero-runner
+
+# With custom Redis
+herorunner my-hero-runner --redis-url redis://custom:6379
+```
+
+## Job Payload
+
+The payload should contain the heroscript content:
+
+```heroscript
+!!git.list
+print("Repositories listed")
+!!docker.ps
+```
+
+## Examples
+
+### Simple Print
+```heroscript
+print("Hello from heroscript!")
+```
+
+### Hero Actions
+```heroscript
+!!git.list
+!!docker.start name:"myapp"
+```
+
+### With Environment Variables
+```json
+{
+  "payload": "print(env.MY_VAR)",
+  "env_vars": {
+    "MY_VAR": "Hello World"
+  }
+}
+```
+
+## Requirements
+
+- `hero` CLI must be installed and in PATH
+- Redis server accessible
+- Valid job signatures
+
+## Error Handling
+
+- **Hero CLI Not Found**: Returns error if `hero` command unavailable
+- **Timeout**: Kills process if timeout exceeded
+- **Non-zero Exit**: Returns error with hero CLI output
+- **Invalid Signature**: Rejects job before execution