feat: Add examples for workflows, pipelines, and agents with YAML/JSON support

- Introduced `workflow.yaml` and `pipeline.yaml` examples demonstrating quick-start configurations for workflows and pipelines.
- Added `agent.json` and `hackernews_agent.yaml` to showcase detailed agent setups with LLM-based prompt handling and HackerNews API integration.
- Added documentation (`docs/logo_ascii.md`, `docs/persistence.md`) explaining logo rendering, persistence providers, and their configurations.
- Expanded resource capabilities: increased memory limits (4GB) and adjusted network/security policies (connection rates, seccomp filters).
- Updated dependencies: added `serde_yaml` for YAML parsing.

Author: dpsoft

Cargo.lock

@@ -60,6 +60,7 @@ tracing = "0.1"
 tracing-subscriber = { version = "0.3", features = ["env-filter"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_yaml = "0.9"
 void-box-protocol = { path = "void-box-protocol" }
 libc = "0.2"
 nix = { version = "0.29", features = ["fs", "ioctl", "net", "socket", "event"] }

Cargo.toml

@@ -0,0 +1,69 @@
+# VoidBox Event Model (Skill + Environment)
+
+The event stream is designed so every action can be answered as:
+
+- Which `run`?
+- Which `box` (if any)?
+- Which `skill`?
+- In which `environment`?
+- What happened (`event_type`)?
+
+## Core Fields
+
+All events include:
+
+- `ts_ms`
+- `level`
+- `event_type`
+- `message`
+- `run_id`
+
+Optional identity/correlation fields:
+
+- `box_name`
+- `skill_id`
+- `skill_type`
+- `environment_id`
+- `mode` (`mock|local|auto`)
+- `stream` (`stdout|stderr`)
+- `seq`
+- `payload`
+
+## Event Types
+
+Lifecycle:
+
+- `run.started`
+- `run.spec.loaded`
+- `run.finished`
+- `run.failed`
+- `run.cancelled`
+
+Environment:
+
+- `env.provisioned`
+
+Box / workflow planning:
+
+- `box.started`
+- `workflow.planned`
+
+Skills:
+
+- `skill.mounted`
+
+Streams/logs:
+
+- `log.chunk`
+- `log.closed`
+
+## TUI Mapping
+
+A Claude-like TUI should render this stream in a timeline:
+
+- `skill.mounted` -> capability setup
+- `env.provisioned` -> sandbox context
+- `log.chunk` -> live execution detail
+- `run.finished|run.failed` -> terminal status
+
+This keeps `voidbox = skill + environment` visible in every run.

docs/event_model.md

@@ -0,0 +1,43 @@
+# TUI Logo from PNG (ASCII)
+
+You can render the real Void-Box image in terminal TUI as ASCII art.
+
+## 1) Convert image to ASCII
+
+```bash
+scripts/logo_to_ascii.sh /path/to/void-box-logo.png assets/logo/void-box.txt 80
+```
+
+The script tries:
+
+- `chafa` (preferred)
+- `jp2a` (fallback)
+
+## 2) Run TUI with logo
+
+Default path (auto-loaded):
+
+- `assets/logo/void-box.txt`
+
+Run:
+
+```bash
+cargo run --bin voidbox -- tui
+```
+
+Or explicit path:
+
+```bash
+cargo run --bin voidbox -- tui --logo-ascii assets/logo/void-box.txt
+```
+
+Or env var:
+
+```bash
+VOIDBOX_LOGO_ASCII_PATH=assets/logo/void-box.txt cargo run --bin voidbox -- tui
+```
+
+## Notes
+
+- `--logo-ascii` is supported by the TUI command (`voidbox tui`).
+- If no file exists, TUI falls back to `⬢ VOID-BOX`.

docs/logo_ascii.md

@@ -0,0 +1,48 @@
+# Persistence Providers
+
+`void-box` now supports a persistence abstraction for daemon state and TUI conversation history.
+
+## Provider Abstraction
+
+Code: `src/persistence.rs`
+
+Trait:
+
+- `load_runs()`
+- `save_run()`
+- `append_session_message()`
+- `load_session_messages()`
+
+Built-in providers:
+
+- `disk` (default): persists to local files under:
+  - `~/.local/state/void-box/runs/*.json`
+  - `~/.local/state/void-box/sessions/*.jsonl`
+- `sqlite` (example adapter): currently delegates to disk provider and shows where a real SQLite backend plugs in.
+- `valkey` (example adapter): currently delegates to disk provider and shows where a real Valkey/Redis backend plugs in.
+
+## Selecting a Provider
+
+```bash
+# default
+VOIDBOX_PERSISTENCE_PROVIDER=disk
+
+# example adapters
+VOIDBOX_PERSISTENCE_PROVIDER=sqlite
+VOIDBOX_PERSISTENCE_PROVIDER=valkey
+```
+
+Optional state directory override:
+
+```bash
+VOIDBOX_STATE_DIR=/tmp/void-box-state
+```
+
+## Conversation Persistence
+
+Daemon endpoints:
+
+- `POST /v1/sessions/:id/messages`
+- `GET /v1/sessions/:id/messages`
+
+The TUI writes user/assistant interactions to these endpoints and can show them with `/history`.

docs/persistence.md

@@ -65,6 +65,38 @@ Interactive/demo style Claude-compatible session.
 cargo run --example claude_in_voidbox_example
 ```
 
+## hackernews
+
+HackerNews research agent with a real procedural-knowledge skill (`hackernews-api.md`)
+that teaches the agent HOW to use the HN API via curl + jq.
+
+Build a production initramfs (real `claude-code`):
+
+```bash
+CLAUDE_CODE_BIN=/path/to/claude scripts/build_guest_image.sh
+```
+
+Then set runtime image env:
+
+```bash
+export VOID_BOX_KERNEL=/boot/vmlinuz-$(uname -r)
+export VOID_BOX_INITRAMFS=target/void-box-rootfs.cpio.gz
+```
+
+Run the HackerNews agent spec (Claude default):
+
+```bash
+cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml
+```
+
+Run with Ollama (no spec edits needed):
+
+```bash
+VOIDBOX_LLM_PROVIDER=ollama \
+VOIDBOX_LLM_MODEL=qwen2.5-coder:7b \
+cargo run --bin voidbox -- run --file examples/hackernews/hackernews_agent.yaml
+```
+
 ## playground_pipeline
 
 Observability-first pipeline for Grafana LGTM with OTLP export.

examples/README.md

@@ -0,0 +1,23 @@
+api_version: v1
+kind: agent
+name: hn_researcher
+
+sandbox:
+  mode: auto
+  memory_mb: 1024
+  vcpus: 1
+  network: true
+
+llm:
+  provider: claude
+
+agent:
+  prompt: >
+    Analyze the current HackerNews top stories and produce a tactical briefing
+    for AI engineering teams. Group stories by theme, prioritize by engagement
+    density (score/time, comments/time), and extract 3-5 actionable signals.
+    Output a clean markdown report with sections: Top Signals, Emerging Themes,
+    and Watchlist (next 24h). Include source links.
+  skills:
+    - "file:examples/hackernews/skills/hackernews-api.md"
+  timeout_secs: 600