hermes-soul: auto-provision SOUL.md from HERMES.md via setup-hermes-soul.sh

- tools/setup-hermes-soul.sh: new auto-setup script (no-op on non-Hermes)
- HERMES.md: canonical persona for all agent types, agent-type table
- AGENTS.md: auto-setup section lists both caveman and hermes-soul
- post-pull.sh runs it automatically on every sync

AGENTS.md

@@ -94,6 +94,10 @@ Currently auto-setup:
 - **Caveman + templates** (`tools/setup-caveman.sh`): Installs Caveman npm
   package, wrapper scripts, and compact output templates for token-efficient
   CLI output. Wrapper at `~/bin/caveman_wrapper.sh`.
+- **Hermes agent persona** (`tools/setup-hermes-soul.sh`): Provisions
+  `~/.hermes/SOUL.md` from `HERMES.md` on Hermes agents. This ensures every
+  Hermes agent follows the canonical homelab persona (token efficiency, source
+  of truth hierarchy). No-op on non-Hermes agents.
 
 To add a new auto-setup, create `tools/<name>.setup.sh` in the repo,
 commit and push. All enrolled clients pick it up within 5 minutes.

HERMES.md

@@ -1,7 +1,33 @@
-# HERMES.md — Agent persona for Goose sessions on homelab clients
+# HERMES.md — Agent persona for homelab clients
 
-You are running on a machine in the **hubris** homelab. Your primary context
+This file is the canonical agent persona for **all** AI agents running on
-is `/opt/homelab-context/AGENTS.md` — read that first.
+machines in the **hubris** homelab. It prescribes behaviour, token-efficiency
+conventions, and the source-of-truth hierarchy.
+
+## Source of truth
+
+The homelab-context repo at `/opt/homelab-context/` is the single source of
+truth for:
+- Fleet topology (`inventory.yaml`, `hosts/*.yaml`)
+- Service endpoints and credentials (via `homelab secret`)
+- Agent behaviour and conventions
+- Everything in this file
+
+When in doubt, check `/opt/homelab-context/` first.
+
+## Agent type — how this file gets loaded
+
+| Agent | Loading mechanism |
+|-------|------------------|
+| **Hermes** | `tools/setup-hermes-soul.sh` (auto-setup) → provisions `~/.hermes/SOUL.md` from this file |
+| **Goose** | `.goosehints` symlink at `~/.config/goose/.goosehints` → `/opt/homelab-context/HERMES.md` |
+| **Claude Code / Codex** | Symlink or copy this file into the project's `CLAUDES.md` / `.claude` instructions |
+
+**Do not edit SOUL.md or .goosehints directly.** Edit this file in the
+homelab-context repo instead. Changes propagate to all clients on the next
+sync (`sudo homelab sync`).
+
+---
 
 ## Token efficiency (caveman skill)
 
@@ -31,8 +57,8 @@ https://github.com/adityahimaone/hermes-agent-rtk-caveman.
 ### Templates
 
 Caveman templates live at `~/templates/`:
-- `git_status.txt` — compact status format
+- `git_status.txt` — compact git status format
-- `git_log.txt` — compact log format
+- `git_log.txt` — compact git log format
 - `lint_results.txt` — compact ESLint format
 - `test_results.txt` — compact vitest/jest format
 
@@ -42,9 +68,16 @@ Caveman templates live at `~/templates/`:
 - Commands with no output — skip entirely
 - When you need the exact raw output for post-processing
 
-## Verification
+### Verification
 
 ```bash
-# Check caveman is installed
 ls ~/bin/caveman_wrapper.sh && echo "caveman ready"
 ```
+
+## Important note for Hermes agents
+
+If you are reading this as a Hermes agent, your SOUL.md was auto-provisioned
+by `tools/setup-hermes-soul.sh`. This file is the canonical original — you
+can verify the content matches or re-provision by running:
+
+    bash /opt/homelab-context/tools/setup-hermes-soul.sh

tools/setup-hermes-soul.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# setup-hermes-soul.sh — auto-provisions Hermes SOUL.md from canonical HERMES.md.
+# Runs automatically after every homelab-context git pull (via tools/post-pull.sh).
+#
+# What it does:
+#   - Detects if Hermes Agent is installed (~/.hermes/SOUL.md exists)
+#   - If yes, copies the canonical HERMES.md content into SOUL.md with
+#     an auto-generated header that declares /opt/homelab-context as source of truth
+#   - Idempotent — re-running re-copies if HERMES.md content changed
+#
+# For non-Hermes agents (Goose, Claude Code, etc.), this script is a no-op.
+# Those agents use the `.goosehints` symlink mechanism instead.
+
+set -euo pipefail
+
+CONTEXT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+HERMES_MD="$CONTEXT_DIR/HERMES.md"
+SOUL_MD="${HOME}/.hermes/SOUL.md"
+
+# Colors for output (only when connected to a terminal)
+if [ -t 1 ]; then
+  GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+else
+  GREEN=''; YELLOW=''; NC=''
+fi
+ok()   { echo -e "${GREEN}[hermes-soul]${NC} $1"; }
+skip() { echo -e "${YELLOW}[hermes-soul]${NC} $1"; }
+
+# --- 1. Check if Hermes is installed ---
+if [ ! -f "$SOUL_MD" ]; then
+  skip "hermes not installed (~/.hermes/SOUL.md not found) — skipping"
+  exit 0
+fi
+
+# --- 2. Check if canonical HERMES.md exists ---
+if [ ! -f "$HERMES_MD" ]; then
+  echo "[hermes-soul] WARNING: $HERMES_MD not found — skipping"
+  exit 0
+fi
+
+# --- 3. Write SOUL.md with canon source header + HERMES.md content ---
+{
+  echo "# Hermes Agent Persona — homelab agent (${HOSTNAME:-$(hostname -s 2>/dev/null || echo 'unknown')})"
+  echo ""
+  echo "You are an AI agent running in the **hubris** homelab."
+  echo ""
+  cat << 'PRE'
+## Source of truth
+
+The homelab-context repo at `/opt/homelab-context/` is the single source of truth for:
+- Fleet topology (`inventory.yaml`, `hosts/*.yaml`)
+- Service endpoints and credentials
+- Agent behaviour and conventions
+
+This SOUL.md is auto-generated from `/opt/homelab-context/HERMES.md` by
+`tools/setup-hermes-soul.sh`. Do not edit SOUL.md directly — edit HERMES.md
+in the homelab-context repo instead. Changes propagate automatically on the
+next sync or by running:
+
+    sudo homelab sync
+
+---
+
+PRE
+  cat "$HERMES_MD"
+} > "$SOUL_MD"
+
+ok "SOUL.md provisioned from HERMES.md ($(wc -l < "$SOUL_MD") lines)"