tools: post-pull auto-setup hook + caveman (RTK-style token optimization)

AGENTS.md

@@ -83,7 +83,24 @@ Grep is fine for browsing or when MCP is unreachable.
 - **Wiki updates**: same-session rule applies to any meaningful state change
   this client makes.
 
-## 6. When in doubt
+## 6. Auto-setup mechanism
+
+The homelab-context repo ships tooling that gets automatically installed
+on every client after `git pull`. This is handled by `tools/post-pull.sh`
+(replaces the raw git pull in the sync timer) which runs any script matching
+`tools/*.setup.sh` after pull.
+
+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`.
+
+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.
+
+To trigger sync manually: `sudo homelab sync` or wait for the 5-min timer.
+
+## 7. When in doubt
 
 Run `homelab mcp search_docs <query>` or `homelab mcp get_host <name>`.
 The clone is the fallback; MCP is the index.

operations/hermes-agent.md

@@ -190,9 +190,20 @@ every tool call, use `approve`. See
    node. The wrapper, persona, and MCP wiring stay unchanged; only
    `GOOSE_PROVIDER`/`GOOSE_MODEL` change.
 
+7. **Caveman auto-setup via post-pull hook.** The sync timer now calls
+   `tools/post-pull.sh`, which runs any `tools/*.setup.sh` after git pull.
+   Currently this auto-installs the Caveman npm package, wrapper scripts, and
+   compact output templates on all agent hosts (*token efficiency*).
+
 ## Changelog
 
-### 2026-05-31 — initial page
+### 2026-06-01 — caveman + post-pull auto-setup
+Added `tools/post-pull.sh` sync hook that auto-runs `tools/*.setup.sh`
+after every git pull. First user: `tools/setup-caveman.sh` installed Caveman
+templating + `~/bin/caveman_wrapper.sh` + `~/templates/*.txt` for token-
+efficient CLI output. Replaces raw `git pull` in launchd/systemd timers.
+Also created `tools/caveman/` with the wrapper script, JS renderer, and
+templates — the canonical source for all agent hosts.
 Captures the Hermes-on-Goose onboarding flow added in the same commit as
 `bootstrap.sh --with-hermes`, `bin/hermes`, the sops rule for
 `secrets/openrouter-api-key.yaml`, and the `homelab client add --with-hermes`

scripts/sync/linux/homelab-context-sync.service

@@ -1,13 +1,12 @@
 [Unit]
-Description=Pull /opt/homelab-context from Gitea
+Description=Pull /opt/homelab-context from Gitea + auto-setup tooling
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=oneshot
-ExecStart=/usr/bin/git -C /opt/homelab-context pull --ff-only --quiet
+ExecStart=/usr/bin/env bash /opt/homelab-context/tools/post-pull.sh
 TimeoutStartSec=60
-# Don't fail aggressively — a missed pull just retries next tick.
 SuccessExitStatus=0 1
 Nice=10
 

scripts/sync/macos/network.hubris.homelab-context-sync.plist

@@ -7,12 +7,9 @@
 
     <key>ProgramArguments</key>
     <array>
-        <string>/usr/bin/git</string>
-        <string>-C</string>
-        <string>/opt/homelab-context</string>
-        <string>pull</string>
-        <string>--ff-only</string>
-        <string>--quiet</string>
+        <string>/usr/bin/env</string>
+        <string>bash</string>
+        <string>/opt/homelab-context/tools/post-pull.sh</string>
     </array>
 
     <key>StartInterval</key>

tools/post-pull.sh

@@ -12,12 +12,18 @@ CONTEXT_DIR="${HOMELAB_CONTEXT_DIR:-/opt/homelab-context}"
 
 # Git safe.directory workaround: the repo is owned by the regular user
 # but launchd runs as root. Run git as the repo owner.
-REPO_OWNER=$(stat -f "%Su" "$(readlink -f "$CONTEXT_DIR")" 2>/dev/null || \
-  stat -f "%Su" "/Users/dtoro/Homelab-Docs" 2>/dev/null || echo "root")
+if command -v realpath &>/dev/null; then
+  REPO_REAL=$(realpath "$CONTEXT_DIR")
+elif command -v grealpath &>/dev/null; then
+  REPO_REAL=$(grealpath "$CONTEXT_DIR")
+else
+  REPO_REAL=$(perl -e 'print Cwd::abs_path(shift)' "$CONTEXT_DIR" 2>/dev/null || echo "/Users/dtoro/Homelab-Docs")
+fi
+REPO_OWNER=$(stat -f "%Su" "$REPO_REAL" 2>/dev/null || echo "dtoro")
 
 # 1. Git pull (as repo owner to avoid safe.directory issues)
 if [ "$REPO_OWNER" != "root" ] && command -v sudo &>/dev/null; then
-  sudo -u "$REPO_OWNER" git -C "$CONTEXT_DIR" pull --ff-only --quiet 2>&1 || \
+  sudo -u "$REPO_OWNER" git -C "$CONTEXT_DIR" pull --ff-only --quiet 2>&1 | grep -v "failed to store" || \
     echo "[post-pull] git pull failed (network?) continuing..."
 else
   git -C "$CONTEXT_DIR" pull --ff-only --quiet 2>&1 || \