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

docs/runner/osiris.md

@@ -0,0 +1,142 @@
+# Osiris Runner
+
+Database-backed runner for structured data storage and retrieval.
+
+## Overview
+
+The Osiris runner executes Rhai scripts with access to a model-based database system, enabling structured data operations and persistence.
+
+## Features
+
+- **Rhai Scripting**: Execute Rhai scripts with Osiris database access
+- **Model-Based Storage**: Define and use data models
+- **CRUD Operations**: Create, read, update, delete records
+- **Query Support**: Search and filter data
+- **Schema Validation**: Type-safe data operations
+- **Transaction Support**: Atomic database operations
+
+## Usage
+
+```bash
+# Start the runner
+runner_osiris my-osiris-runner
+
+# With custom Redis
+runner_osiris my-osiris-runner --redis-url redis://custom:6379
+```
+
+## Job Payload
+
+The payload should contain a Rhai script using Osiris operations:
+
+```rhai
+// Example: Store data
+let model = osiris.model("users");
+let user = model.create(#{
+    name: "Alice",
+    email: "alice@example.com",
+    age: 30
+});
+print(user.id);
+
+// Example: Retrieve data
+let found = model.get(user.id);
+print(found.name);
+```
+
+## Examples
+
+### Create Model and Store Data
+```rhai
+// Define model
+let posts = osiris.model("posts");
+
+// Create record
+let post = posts.create(#{
+    title: "Hello World",
+    content: "First post",
+    author: "Alice",
+    published: true
+});
+
+print(`Created post with ID: ${post.id}`);
+```
+
+### Query Data
+```rhai
+let posts = osiris.model("posts");
+
+// Find by field
+let published = posts.find(#{
+    published: true
+});
+
+for post in published {
+    print(post.title);
+}
+```
+
+### Update Records
+```rhai
+let posts = osiris.model("posts");
+
+// Get record
+let post = posts.get("post-123");
+
+// Update fields
+post.content = "Updated content";
+posts.update(post);
+```
+
+### Delete Records
+```rhai
+let posts = osiris.model("posts");
+
+// Delete by ID
+posts.delete("post-123");
+```
+
+### Transactions
+```rhai
+osiris.transaction(|| {
+    let users = osiris.model("users");
+    let posts = osiris.model("posts");
+    
+    let user = users.create(#{ name: "Bob" });
+    let post = posts.create(#{
+        title: "Bob's Post",
+        author_id: user.id
+    });
+    
+    // Both operations commit together
+});
+```
+
+## Data Models
+
+Models are defined dynamically through Rhai scripts:
+
+```rhai
+let model = osiris.model("products");
+
+// Model automatically handles:
+// - ID generation
+// - Timestamps (created_at, updated_at)
+// - Schema validation
+// - Indexing
+```
+
+## Requirements
+
+- Redis server accessible
+- Osiris database configured
+- Valid job signatures
+- Sufficient storage for data operations
+
+## Use Cases
+
+- **Configuration Storage**: Store application configs
+- **User Data**: Manage user profiles and preferences
+- **Workflow State**: Persist workflow execution state
+- **Metrics & Logs**: Store structured logs and metrics
+- **Cache Management**: Persistent caching layer

docs/runner/overview.md

@@ -0,0 +1,96 @@
+# Runners Overview
+
+Runners are the execution layer in the Horus architecture. They receive jobs from the Supervisor via Redis queues and execute the actual workload.
+
+## Architecture
+
+```
+Supervisor → Redis Queue → Runner → Execute Job → Return Result
+```
+
+## Available Runners
+
+Horus provides three specialized runners:
+
+### 1. **Hero Runner**
+Executes heroscripts using the Hero CLI ecosystem.
+
+**Use Cases:**
+- Running Hero automation tasks
+- Executing heroscripts from job payloads
+- Integration with Hero CLI tools
+
+**Binary:** `herorunner`
+
+[→ Hero Runner Documentation](./hero.md)
+
+### 2. **SAL Runner**
+System Abstraction Layer runner for system-level operations.
+
+**Use Cases:**
+- OS operations (file, process, network)
+- Infrastructure management (Kubernetes, VMs)
+- Cloud provider operations (Hetzner)
+- Database operations (Redis, Postgres)
+
+**Binary:** `runner_sal`
+
+[→ SAL Runner Documentation](./sal.md)
+
+### 3. **Osiris Runner**
+Database-backed runner for data storage and retrieval using Rhai scripts.
+
+**Use Cases:**
+- Structured data storage
+- Model-based data operations
+- Rhai script execution with database access
+
+**Binary:** `runner_osiris`
+
+[→ Osiris Runner Documentation](./osiris.md)
+
+## Common Features
+
+All runners implement the `Runner` trait and provide:
+
+- **Job Execution**: Process jobs from Redis queues
+- **Signature Verification**: Verify job signatures before execution
+- **Timeout Support**: Respect job timeout settings
+- **Environment Variables**: Pass environment variables to jobs
+- **Error Handling**: Comprehensive error reporting
+- **Logging**: Structured logging for debugging
+
+## Runner Protocol
+
+Runners communicate with the Supervisor using a Redis-based protocol:
+
+1. **Job Queue**: Supervisor pushes jobs to `runner:{runner_id}:jobs`
+2. **Job Processing**: Runner pops job, validates signature, executes
+3. **Result Storage**: Runner stores result in `job:{job_id}:result`
+4. **Status Updates**: Runner updates job status throughout execution
+
+## Starting a Runner
+
+```bash
+# Hero Runner
+herorunner <runner_id> [--redis-url <url>]
+
+# SAL Runner
+runner_sal <runner_id> [--redis-url <url>]
+
+# Osiris Runner
+runner_osiris <runner_id> [--redis-url <url>]
+```
+
+## Configuration
+
+All runners accept:
+- `runner_id`: Unique identifier for the runner (required)
+- `--redis-url`: Redis connection URL (default: `redis://localhost:6379`)
+
+## Security
+
+- Jobs must be cryptographically signed
+- Runners verify signatures before execution
+- Untrusted jobs are rejected
+- Environment variables should not contain sensitive data in production

docs/runner/sal.md

@@ -0,0 +1,123 @@
+# SAL Runner
+
+System Abstraction Layer runner for system-level operations.
+
+## Overview
+
+The SAL runner executes Rhai scripts with access to system abstraction modules for OS operations, infrastructure management, and cloud provider interactions.
+
+## Features
+
+- **Rhai Scripting**: Execute Rhai scripts with SAL modules
+- **System Operations**: File, process, and network management
+- **Infrastructure**: Kubernetes, VM, and container operations
+- **Cloud Providers**: Hetzner and other cloud integrations
+- **Database Access**: Redis and Postgres client operations
+- **Networking**: Mycelium and network configuration
+
+## Available SAL Modules
+
+### Core Modules
+- **sal-os**: Operating system operations
+- **sal-process**: Process management
+- **sal-text**: Text processing utilities
+- **sal-net**: Network operations
+
+### Infrastructure
+- **sal-virt**: Virtualization management
+- **sal-kubernetes**: Kubernetes cluster operations
+- **sal-zinit-client**: Zinit process manager
+
+### Storage & Data
+- **sal-redisclient**: Redis operations
+- **sal-postgresclient**: PostgreSQL operations
+- **sal-vault**: Secret management
+
+### Networking
+- **sal-mycelium**: Mycelium network integration
+
+### Cloud Providers
+- **sal-hetzner**: Hetzner cloud operations
+
+### Version Control
+- **sal-git**: Git repository operations
+
+## Usage
+
+```bash
+# Start the runner
+runner_sal my-sal-runner
+
+# With custom Redis
+runner_sal my-sal-runner --redis-url redis://custom:6379
+```
+
+## Job Payload
+
+The payload should contain a Rhai script using SAL modules:
+
+```rhai
+// Example: List files
+let files = os.list_dir("/tmp");
+print(files);
+
+// Example: Process management
+let pid = process.spawn("ls", ["-la"]);
+let output = process.wait(pid);
+print(output);
+```
+
+## Examples
+
+### File Operations
+```rhai
+// Read file
+let content = os.read_file("/path/to/file");
+print(content);
+
+// Write file
+os.write_file("/path/to/output", "Hello World");
+```
+
+### Kubernetes Operations
+```rhai
+// List pods
+let pods = k8s.list_pods("default");
+for pod in pods {
+    print(pod.name);
+}
+```
+
+### Redis Operations
+```rhai
+// Set value
+redis.set("key", "value");
+
+// Get value
+let val = redis.get("key");
+print(val);
+```
+
+### Git Operations
+```rhai
+// Clone repository
+git.clone("https://github.com/user/repo", "/tmp/repo");
+
+// Get status
+let status = git.status("/tmp/repo");
+print(status);
+```
+
+## Requirements
+
+- Redis server accessible
+- System permissions for requested operations
+- Valid job signatures
+- SAL modules available in runtime
+
+## Security Considerations
+
+- SAL operations have system-level access
+- Jobs must be from trusted sources
+- Signature verification is mandatory
+- Limit runner permissions in production