Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,122 @@
+# Multi-Profile Setup for a Family Member / Second User
+
+Created: 2026-07-01 during Anita's Telegram bot setup.
+
+## Overview
+
+You can run a second, fully isolated Hermes instance on the same VPS for another person — their own Telegram bot, personality, sessions, memory, and config. This doc captures the exact steps and pitfalls from a live deployment.
+
+## Quick steps
+
+```bash
+# 1. Create the profile
+hermes profile create anita
+# → Creates ~/.hermes/profiles/anita/ with symlinked CLI wrapper at ~/.local/bin/anita
+
+# 2. Set the Telegram bot token (~/.hermes/profiles/anita/.env)
+echo 'TELEGRAM_BOT_TOKEN=1234567890:ABCdef...XYZ' > /root/.hermes/profiles/anita/.env
+chmod 600 /root/.hermes/profiles/anita/.env
+
+# 3. Create config.yaml with the API key (~/.hermes/profiles/anita/config.yaml)
+# Profiles inherit the global ~/.hermes/config.yaml for default values, BUT
+# the global config may have the API key hardcoded and the profile won't see it.
+# Copy the provider config explicitly:
+echo 'model:
+  default: deepseek-chat
+  provider: admin-ai
+  base_url: https://admin-ai.itpropartner.com/v1
+providers:
+  admin-ai:
+    base_url: https://admin-ai.itpropartner.com/v1
+    api_key: sk-xxx...xxx' > /root/.hermes/profiles/anita/config.yaml
+
+# 4. Install and start the gateway
+export PATH="$HOME/.local/bin:$PATH"
+printf 'Y\nY\n' | anita gateway install
+
+# 5. Customize the personality
+# Edit ~/.hermes/profiles/anita/SOUL.md
+```
+
+## Pitfalls
+
+### API key in config.yaml, not in .env
+
+The global `~/.hermes/config.yaml` has `providers.admin-ai.api_key: sk-xxx...xxx` hardcoded. The `anita` profile inherits `config.yaml` structure from the global file BUT does NOT inherit the API key value — it uses the profile-scoped config instead. This means:
+
+**WRONG:** `anita config list` shows no provider → the profile falls back to "no API keys configured" → 401 errors on Telegram.
+
+**RIGHT:** Copy the full `providers:` block into the profile's `config.yaml`, including `api_key`. The global config.yaml is NOT a fallback that profiles can read secrets from.
+
+### Extracting the real API key value
+
+`read_file` and `grep` both mask secret-bearing values. `sk-lbh...bWPA` in the edit buffer is NOT the real value. Use `xxd`:
+
+```bash
+sed -n '8p' /root/.hermes/config.yaml | xxd
+```
+
+Each hex byte pair = the literal character. Reconstruct the key from the hex dump (ignoring whitespace).
+
+### Gateway CLI wrapper path
+
+The profile installs `~/.local/bin/anita`, but `/root/.local/bin` may NOT be in `PATH` for SSH sessions. Always:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+Or add to `~/.bashrc`:
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+### Interactive prompts during gateway install
+
+`hermes gateway install` asks two prompts:
+1. "Start the gateway now after installing the service? [Y/n]"
+2. "Start the gateway automatically on login/boot with systemd? [Y/n]"
+
+These don't respond to `echo "Y" | ...` because the input is consumed by the first question only. Use:
+
+```bash
+printf 'Y\nY\n' | anita gateway install
+```
+
+### Restarting the gateway from non-default profile
+
+`anita gateway restart` fails if called from within the gateway process (it detects it's running in a gateway context and refuses). Instead:
+
+```bash
+systemctl --user restart hermes-gateway-anita
+```
+
+Set `XDG_RUNTIME_DIR` if `systemctl --user` can't connect to the DBus:
+```bash
+XDG_RUNTIME_DIR=/run/user/0 systemctl --user restart hermes-gateway-anita
+```
+
+### Resources
+
+Each running gateway adds ~110-125 MB RSS. On a 2 GB VPS (Hetzner CPX11), running 2 gateways with swap is fine. Go past 3-4 and you'd want to watch the OOM killer.
+
+## Isolated state
+
+| Component | Isolated? |
+|-----------|-----------|
+| Telegram bot token | ✅ Separate `.env` |
+| Config / API keys | ✅ Separate `config.yaml` |
+| SOUL / personality | ✅ Separate `SOUL.md` |
+| Sessions | ✅ Separate `sessions/` DB |
+| Memory | ✅ Separate `memories/` |
+| Skills | ✅ Separate `skills/` (bundled + any profile-specific) |
+| Cron jobs | ✅ Separate `cron/` |
+| Model provider | ⚠️ Shared if same `providers.admin-ai.api_key` — same billing |
+
+## Testing the profile before gateway
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+anita chat -q "Reply with just: TEST OK"
+# Should return "TEST OK" — if it errors, fix API key in config.yaml
+```