docs: add Hermes to README grid + eliminate thin driver wrappers

- Add Hermes column to Claw Type Support matrix (7 drivers)
- Document --context flag for claw build
- Update CLAUDE.md, architecture plan, and UPDATING.md for Phase 4.8
- Remove thin wrapper functions in nanobot, picoclaw, nullclaw,
  microclaw drivers — call shared.* directly
- Fix bare error returns to include driver prefix consistently

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Wojtek Grabski

CLAUDE.md

@@ -37,6 +37,7 @@ Clawdapus is infrastructure-layer governance for AI agent containers. The `claw`
 - `internal/driver/openclaw/` — JSON5-aware config injection, CLAWDAPUS.md generation, skill generation
 - `internal/driver/nanobot/` — Nanobot driver: JSON config, `/root/.nanobot` mounts, container-running health
 - `internal/driver/picoclaw/` — PicoClaw driver: `model_list[]` config, non-root mounts, HTTP `/health` probing
+- `internal/driver/hermes/` — Hermes driver: YAML config, workspace AGENTS.md, SOUL.md persona, cron/jobs.json, gateway health probing
 - `internal/driver/shared/` — Shared model/provider helpers, platform token mapping, CLAWDAPUS.md + handle skill generation
 - `internal/persona/` — Persona materialization: local copy + OCI pull via oras-go
 - `internal/pod/` — claw-pod.yml parser, compose emitter (includes x-claw.include composition)
@@ -59,6 +60,7 @@ Clawdapus is infrastructure-layer governance for AI agent containers. The `claw`
 | Phase 4 — cllama sidecar proxy (standalone + wiring + cost tracking + dashboard) | DONE |
 | Phase 4.5 — Interactive claw init & claw agent add (canonical layout) | DONE |
 | Phase 4.7 — Nanobot + PicoClaw drivers, shared helpers, scaffold parity | DONE |
+| Phase 4.8 — Hermes driver + shared helper extraction | DONE |
 | v0.2.0 — PERSONA runtime materialization + x-claw.include contract composition | DONE |
 | Phase 4.6 — Unified worker architecture (config, provision, diagnostic) | DESIGN |
 | Phase 5 — Drift scoring + cllama policy pipeline | NOT STARTED |
@@ -101,7 +103,8 @@ Clawdapus is infrastructure-layer governance for AI agent containers. The `claw`
 - **Nanobot driver**: Config at `/root/.nanobot/config.json`, workspace at `/root/.nanobot/workspace`, cron at `/root/.nanobot/cron/jobs.json`. CONFIGURE DSL: `nanobot config set <path> <value>`. Container-running health only (no HTTP endpoint). MVP channels: discord, telegram, slack
 - **PicoClaw driver**: Non-root user (`USER picoclaw`); mounts at `/home/picoclaw/.picoclaw` with `PICOCLAW_HOME`/`PICOCLAW_CONFIG` env overrides. Model-centric config: `model_list[]` with `model` field (e.g. `openai/<ref>` under cllama) + `agents.defaults.model_name`. HTTP `/health` + `/ready` on port 18790. Requires at least one supported HANDLE (fail-closed, matching upstream). 13 supported platforms including long-tail set
 - **Shared driver helpers** (`internal/driver/shared/`): `SplitModelRef`, `CollectProviders`, `NormalizeProvider`, `ResolveProviderAPIKey` extracted from microclaw/nullclaw duplication. `PlatformTokenVar` maps 14 platforms to env var names. `GenerateClawdapusMD` and `GenerateHandleSkill` shared across all drivers
-- **INVOKE 5-field cron only**: Both nanobot and picoclaw drivers validate and reject non-5-field cron expressions. `at`/`every` syntaxes deferred to future Clawfile parser extension
+- **INVOKE 5-field cron only**: Nanobot, picoclaw, and hermes drivers validate and reject non-5-field cron expressions. `at`/`every` syntaxes deferred to future Clawfile parser extension
+- **Hermes driver**: Two-root layout (`/root/.hermes` + `/workspace`). YAML config (`config.yaml`) + dotenv (`.env`). Effective `AGENTS.md` inlines CLAWDAPUS.md as infrastructure context. PERSONA via `SOUL.md` copy. INVOKE translates to Hermes-native `cron/jobs.json` with deterministic SHA256 IDs. cllama via `OPENAI_BASE_URL`/`OPENAI_API_KEY` in `.env`. Gateway health: `hermes gateway status || pgrep` fallback. Scoped to discord/telegram/slack (fail-closed on unsupported). Scaffold deferred until stable base image exists
 - **PERSONA runtime materialization**: `PERSONA <ref>` in Clawfile emits `claw.persona.default` label; `x-claw.persona` overrides at pod level. Local paths (relative, absolute, `file://`) are copied with path-traversal + symlink checks. Non-local refs pulled as OCI artifacts via oras-go. Mounted writable into runner; `CLAW_PERSONA_DIR` env set only when persona is present. Currently a deploy-time mount mechanism — not yet a complete identity system (no memory restoration, no snapshotting, no registry round-trips)
 - **x-claw.include contract composition**: `include` array in x-claw block modularizes the behavioral contract. Modes: `enforce` (hard rules, inlined), `guide` (recommendations, inlined), `reference` (informational, mounted as read-only skill files). ADR-009
 

README.md

@@ -177,7 +177,7 @@ Clawdapus extends two formats you already know:
 | `claw agent add` | _(none)_ | Add agents while preserving existing layout (`--layout auto|canonical|flat`) |
 | `Clawfile` | `Dockerfile` | Build an immutable agent image |
 | `claw-pod.yml` | `docker-compose.yml` | Run a governed agent fleet |
-| `claw build` | `docker build` | Transpile + build OCI image |
+| `claw build` | `docker build` | Transpile + build OCI image (`--context` for separate build context) |
 | `claw up` | `docker compose up` | Enforce + deploy |
 
 Any valid Dockerfile is a valid Clawfile. Any valid `docker-compose.yml` is a valid `claw-pod.yml`. Extended directives live in namespaces Docker already ignores. Eject from Clawdapus anytime — you still have a working OCI image and a working compose file.
@@ -190,7 +190,7 @@ The Clawfile extends the Dockerfile with directives that the `claw build` prepro
 
 | Directive | Purpose |
 |---|---|
-| `CLAW_TYPE` | Selects the runtime driver (openclaw, nanobot, picoclaw, nanoclaw, microclaw, nullclaw) |
+| `CLAW_TYPE` | Selects the runtime driver (openclaw, hermes, nanobot, picoclaw, nanoclaw, microclaw, nullclaw) |
 | `AGENT` | Names the behavioral contract file |
 | `PERSONA` | Imports a persona workspace — local path or OCI artifact ref |
 | `MODEL` | Binds named model slots to providers |
@@ -210,23 +210,23 @@ The Clawfile extends the Dockerfile with directives that the `claw build` prepro
 
 Pick a driver based on what you need. All drivers support `MODEL`, `AGENT`, `CLLAMA`, and `CONFIGURE`.
 
-| | `openclaw` | `nanoclaw` | `nanobot` | `picoclaw` | `nullclaw` | `microclaw` |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| **Runtime** | [OpenClaw](https://openclaw.ai) | [Claude Agent SDK](https://github.com/anthropics/claude-code) | [Nanobot](https://github.com/HKUDS/nanobot) | [PicoClaw](https://github.com/sipeed/picoclaw) | [NullClaw](https://github.com/nullclaw/nullclaw) | [MicroClaw](https://github.com/microclaw/microclaw) |
-| `claw init` scaffold | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| HANDLE: Discord | ✅ | — | ✅ | ✅ | ✅ | ✅ |
-| HANDLE: Telegram | — | — | ✅ | ✅ | ✅ | ✅ |
-| HANDLE: Slack | — | — | ✅ | ✅ | ✅ | ✅ |
-| HANDLE: long-tail ¹ | — | — | — | ✅ | — | — |
-| INVOKE (cron) | ✅ | — | ✅ | ✅ | ✅ | — |
-| Structured health | ✅ | — | — | ✅ | ✅ | — |
-| Read-only rootfs | ✅ | — | ✅ | ✅ | ✅ | — |
-| Non-root container | — | — | — | ✅ | — | — |
-
-Ordered by current upstream repo popularity as of March 8, 2026.
+| | `openclaw` | `hermes` | `nanoclaw` | `nanobot` | `picoclaw` | `nullclaw` | `microclaw` |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| **Runtime** | [OpenClaw](https://openclaw.ai) | [Hermes](https://github.com/hermes-ai/hermes) | [Claude Agent SDK](https://github.com/anthropics/claude-code) | [Nanobot](https://github.com/HKUDS/nanobot) | [PicoClaw](https://github.com/sipeed/picoclaw) | [NullClaw](https://github.com/nullclaw/nullclaw) | [MicroClaw](https://github.com/microclaw/microclaw) |
+| `claw init` scaffold | ✅ | — ² | ✅ | ✅ | ✅ | ✅ | ✅ |
+| HANDLE: Discord | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| HANDLE: Telegram | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| HANDLE: Slack | — | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| HANDLE: long-tail ¹ | — | — | — | — | ✅ | — | — |
+| INVOKE (cron) | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |
+| Structured health | ✅ | ✅ | — | — | ✅ | ✅ | — |
+| Read-only rootfs | ✅ | ✅ | — | ✅ | ✅ | ✅ | — |
+| Non-root container | — | — | — | — | ✅ | — | — |
+
 ¹ PicoClaw long-tail: WhatsApp, Feishu, LINE, QQ, DingTalk, OneBot, WeCom, WeCom App, Pico, MaixCam.
+² Hermes scaffold deferred until a stable base image is available; driver is fully functional via `claw build` + `claw up`.
 
-`claw init` also scaffolds `generic` (alpine:3.20, no driver enforcement) for custom runtimes.
+`claw init` scaffolds `generic` (alpine:3.20, no driver enforcement) for custom runtimes.
 
 ### OpenClaw Discord Routing Compatibility
 
@@ -436,6 +436,7 @@ Bots install things. That's how real work gets done. Tracked mutation is evoluti
 | Phase 4 — Shared governance proxy integration + credential starvation | Done |
 | Phase 4.5 — Interactive claw init & claw agent add (canonical layout) | Done |
 | Phase 4.7 — Nanobot + PicoClaw drivers, shared helpers, scaffold parity | Done |
+| Phase 4.8 — Hermes driver + shared helper extraction | Done |
 | Phase 4.6 — Unified worker architecture (config, provision, diagnostic) | Design |
 | Phase 5 — Drift scoring + fleet governance | Planned |
 | Phase 6 — Recipe promotion + worker mode | Planned |

docs/UPDATING.md

@@ -70,7 +70,7 @@ A planning file can be deleted when:
 
 ---
 
-## Current planning file status (as of 2026-03-08)
+## Current planning file status (as of 2026-03-17)
 
 | File | Status | Action |
 |------|--------|--------|
@@ -79,3 +79,4 @@ A planning file can be deleted when:
 | `2026-02-26-phase4-cllama-sidecar.md` | Shipped scope DONE; policy pipeline deferred to Phase 5 | Keep as reference for deferred policy work |
 | `2026-02-27-worker-architecture-unified.md` | Phase 4.6 DESIGN | Keep; implement next |
 | `2026-03-01-driver-parity-matrix.md` | Implemented (Phase 4.7) | Keep until verified in production |
+| `2026-03-16-hermes-driver-and-shared-refactor.md` | Implemented (Phase 4.8) | Keep until verified in production |

docs/plans/2026-02-18-clawdapus-architecture.md

@@ -21,6 +21,7 @@
 | Phase 4 — cllama sidecar + cost tracking + dashboard | — | **DONE** — standalone proxy, pod wiring, credential starvation, cost hooks, SSE dashboard; policy pipeline deferred to Phase 5 |
 | Phase 4.5 — Interactive claw init & claw agent add | — | **DONE** — canonical layout, layout auto-detection |
 | Phase 4.7 — Nanobot + PicoClaw drivers, scaffold parity | — | **DONE** — 6 driver types, shared helpers, rollcall spike |
+| Phase 4.8 — Hermes driver + shared helper extraction | — | **DONE** — 7 driver types, deeper shared extraction (SetPath, ParseConfigSetCommand, ExecInContainer, IsFiveFieldCron) |
 | v0.2.0 — PERSONA + x-claw.include | — | **DONE** — persona materialization (local + OCI), contract composition (enforce/guide/reference) |
 | Phase 4.6 — Unified worker architecture | — | **DESIGN** — `docs/plans/2026-02-27-worker-architecture-unified.md` |
 | Phase 5 — Drift scoring + cllama policy pipeline | — | NOT STARTED |

internal/driver/microclaw/driver.go

@@ -32,20 +32,18 @@ func (d *Driver) Validate(rc *driver.ResolvedClaw) error {
 		return fmt.Errorf("microclaw driver: agent file %q not found: %w", rc.AgentHostPath, err)
 	}
 
-	modelRef, err := primaryModelRef(rc.Models)
+	modelRef, err := shared.PrimaryModelRef(rc.Models)
 	if err != nil {
-		return err
+		return fmt.Errorf("microclaw driver: %w", err)
 	}
 	provider, _, ok := shared.SplitModelRef(modelRef)
 	if !ok {
 		return fmt.Errorf("microclaw driver: invalid MODEL primary %q (expected provider/model)", modelRef)
 	}
 
-	if len(rc.Configures) > 0 {
-		for _, cmd := range rc.Configures {
-			if _, _, err := parseConfigSetCommand(cmd); err != nil {
-				return fmt.Errorf("microclaw driver: unsupported CONFIGURE command %q: %w", cmd, err)
-			}
+	for _, cmd := range rc.Configures {
+		if _, _, err := parseConfigSetCommand(cmd); err != nil {
+			return fmt.Errorf("microclaw driver: unsupported CONFIGURE command %q: %w", cmd, err)
 		}
 	}
 
@@ -101,7 +99,7 @@ func (d *Driver) Materialize(rc *driver.ResolvedClaw, opts driver.MaterializeOpt
 		if err != nil {
 			return nil, fmt.Errorf("microclaw driver: apply CONFIGURE %q: %w", cmd, err)
 		}
-		if err := setPath(cfg, path, value); err != nil {
+		if err := shared.SetPath(cfg, path, value); err != nil {
 			return nil, fmt.Errorf("microclaw driver: apply CONFIGURE %q: %w", cmd, err)
 		}
 	}
@@ -240,9 +238,9 @@ func (d *Driver) HealthProbe(ref driver.ContainerRef) (*driver.Health, error) {
 }
 
 func generateConfig(rc *driver.ResolvedClaw) (map[string]interface{}, error) {
-	modelRef, err := primaryModelRef(rc.Models)
+	modelRef, err := shared.PrimaryModelRef(rc.Models)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("microclaw driver: %w", err)
 	}
 	provider, modelID, ok := shared.SplitModelRef(modelRef)
 	if !ok {
@@ -343,13 +341,6 @@ func generateConfig(rc *driver.ResolvedClaw) (map[string]interface{}, error) {
 	return cfg, nil
 }
 
-func primaryModelRef(models map[string]string) (string, error) {
-	ref, err := shared.PrimaryModelRef(models)
-	if err != nil {
-		return "", fmt.Errorf("microclaw driver: %w", err)
-	}
-	return ref, nil
-}
 
 func discordAllowedChannels(h *driver.HandleInfo) []uint64 {
 	if h == nil {
@@ -438,6 +429,3 @@ func parseConfigSetCommand(cmd string) (string, interface{}, error) {
 	return path, value, nil
 }
 
-func setPath(obj map[string]interface{}, path string, value interface{}) error {
-	return shared.SetPath(obj, path, value)
-}

internal/driver/nanobot/config.go

@@ -14,15 +14,15 @@ import (
 func GenerateConfig(rc *driver.ResolvedClaw) ([]byte, error) {
 	config := make(map[string]interface{})
 
-	modelRef, err := primaryModelRef(rc.Models)
+	modelRef, err := shared.PrimaryModelRef(rc.Models)
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf("nanobot driver: %w", err)
 	}
 
-	if err := setPath(config, "agents.defaults.model", modelRef); err != nil {
+	if err := shared.SetPath(config, "agents.defaults.model", modelRef); err != nil {
 		return nil, fmt.Errorf("config generation: %w", err)
 	}
-	if err := setPath(config, "agents.defaults.workspace", "/root/.nanobot/workspace"); err != nil {
+	if err := shared.SetPath(config, "agents.defaults.workspace", "/root/.nanobot/workspace"); err != nil {
 		return nil, fmt.Errorf("config generation: %w", err)
 	}
 
@@ -33,17 +33,17 @@ func GenerateConfig(rc *driver.ResolvedClaw) ([]byte, error) {
 		firstProxy := cllama.ProxyBaseURL(rc.Cllama[0])
 		for _, provider := range shared.CollectProviders(rc.Models) {
 			base := "providers." + provider
-			if err := setPath(config, base+".base_url", firstProxy); err != nil {
+			if err := shared.SetPath(config, base+".base_url", firstProxy); err != nil {
 				return nil, fmt.Errorf("config generation: cllama provider %q base_url: %w", provider, err)
 			}
-			if err := setPath(config, base+".api_key", rc.CllamaToken); err != nil {
+			if err := shared.SetPath(config, base+".api_key", rc.CllamaToken); err != nil {
 				return nil, fmt.Errorf("config generation: cllama provider %q api_key: %w", provider, err)
 			}
 		}
 	} else {
 		for _, provider := range shared.CollectProviders(rc.Models) {
 			if token := shared.ResolveProviderAPIKey(provider, rc.Environment); token != "" {
-				if err := setPath(config, "providers."+provider+".api_key", token); err != nil {
+				if err := shared.SetPath(config, "providers."+provider+".api_key", token); err != nil {
 					return nil, fmt.Errorf("config generation: provider %q api_key: %w", provider, err)
 				}
 			}
@@ -53,11 +53,11 @@ func GenerateConfig(rc *driver.ResolvedClaw) ([]byte, error) {
 	for platform, h := range rc.Handles {
 		switch strings.ToLower(platform) {
 		case "discord":
-			if err := setPath(config, "channels.discord.enabled", true); err != nil {
+			if err := shared.SetPath(config, "channels.discord.enabled", true); err != nil {
 				return nil, fmt.Errorf("config generation: HANDLE discord: %w", err)
 			}
 			if token := shared.ResolveEnvTokenFromMap(rc.Environment, "DISCORD_BOT_TOKEN"); token != "" {
-				if err := setPath(config, "channels.discord.token", token); err != nil {
+				if err := shared.SetPath(config, "channels.discord.token", token); err != nil {
 					return nil, fmt.Errorf("config generation: HANDLE discord: %w", err)
 				}
 			}
@@ -67,37 +67,37 @@ func GenerateConfig(rc *driver.ResolvedClaw) ([]byte, error) {
 					if gid == "" {
 						continue
 					}
-					if err := setPath(config, "channels.discord.guild_id", gid); err != nil {
+					if err := shared.SetPath(config, "channels.discord.guild_id", gid); err != nil {
 						return nil, fmt.Errorf("config generation: HANDLE discord: %w", err)
 					}
 					break
 				}
 			}
 		case "telegram":
-			if err := setPath(config, "channels.telegram.enabled", true); err != nil {
+			if err := shared.SetPath(config, "channels.telegram.enabled", true); err != nil {
 				return nil, fmt.Errorf("config generation: HANDLE telegram: %w", err)
 			}
 			if token := shared.ResolveEnvTokenFromMap(rc.Environment, "TELEGRAM_BOT_TOKEN"); token != "" {
-				if err := setPath(config, "channels.telegram.bot_token", token); err != nil {
+				if err := shared.SetPath(config, "channels.telegram.bot_token", token); err != nil {
 					return nil, fmt.Errorf("config generation: HANDLE telegram: %w", err)
 				}
 			}
 		case "slack":
-			if err := setPath(config, "channels.slack.enabled", true); err != nil {
+			if err := shared.SetPath(config, "channels.slack.enabled", true); err != nil {
 				return nil, fmt.Errorf("config generation: HANDLE slack: %w", err)
 			}
 			if token := shared.ResolveEnvTokenFromMap(rc.Environment, "SLACK_BOT_TOKEN"); token != "" {
-				if err := setPath(config, "channels.slack.bot_token", token); err != nil {
+				if err := shared.SetPath(config, "channels.slack.bot_token", token); err != nil {
 					return nil, fmt.Errorf("config generation: HANDLE slack: %w", err)
 				}
 			}
 			if appToken := shared.ResolveEnvTokenFromMap(rc.Environment, "SLACK_APP_TOKEN"); appToken != "" {
-				if err := setPath(config, "channels.slack.app_token", appToken); err != nil {
+				if err := shared.SetPath(config, "channels.slack.app_token", appToken); err != nil {
 					return nil, fmt.Errorf("config generation: HANDLE slack: %w", err)
 				}
 			}
 			if signingSecret := shared.ResolveEnvTokenFromMap(rc.Environment, "SLACK_SIGNING_SECRET"); signingSecret != "" {
-				if err := setPath(config, "channels.slack.signing_secret", signingSecret); err != nil {
+				if err := shared.SetPath(config, "channels.slack.signing_secret", signingSecret); err != nil {
 					return nil, fmt.Errorf("config generation: HANDLE slack: %w", err)
 				}
 			}
@@ -108,30 +108,14 @@ func GenerateConfig(rc *driver.ResolvedClaw) ([]byte, error) {
 
 	// Apply CONFIGURE directives last so operator settings override defaults.
 	for _, cmd := range rc.Configures {
-		path, value, err := parseConfigSetCommand(cmd)
+		path, value, err := shared.ParseConfigSetCommand(cmd, "nanobot")
 		if err != nil {
 			return nil, fmt.Errorf("config generation: %w", err)
 		}
-		if err := setPath(config, path, value); err != nil {
+		if err := shared.SetPath(config, path, value); err != nil {
 			return nil, fmt.Errorf("config generation: %w", err)
 		}
 	}
 
 	return json.MarshalIndent(config, "", "  ")
 }
-
-func parseConfigSetCommand(cmd string) (string, interface{}, error) {
-	return shared.ParseConfigSetCommand(cmd, "nanobot")
-}
-
-func primaryModelRef(models map[string]string) (string, error) {
-	ref, err := shared.PrimaryModelRef(models)
-	if err != nil {
-		return "", fmt.Errorf("nanobot driver: %w", err)
-	}
-	return ref, nil
-}
-
-func setPath(obj map[string]interface{}, path string, value interface{}) error {
-	return shared.SetPath(obj, path, value)
-}