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,54 @@
+# Verification Rules for Infrastructure Changes
+
+## Never invent config keys
+
+If you're about to set a configuration value, confirm the key actually exists in the software first.
+
+**Bad pattern:**
+```
+fallback_providers:
+  - provider: ollama-local
+    model: qwen2.5:7b
+```
+Hermes has no `fallback_providers` key. This silently did nothing. The user rightfully called this out.
+
+**Right pattern:**
+1. Check the software's docs or `--help` for the config option
+2. If docs are offline, check the source code
+3. If you can't confirm it exists, ask the user or use a different approach
+4. A config key that does nothing is worse than no config change at all — it gives false confidence
+
+## Verify before reporting success
+
+Every "should work" assertion that turned out wrong erodes trust. Apply the same bar to config changes that you do to terminal commands:
+
+- Before: "I set fallback_providers, now Hermes will auto-fail over to the local model"
+- After writing the config, check: does the software even have a `fallback_providers` key?
+- After: "do not invent config keys without verifying" — direct user correction
+
+## Key verification for copy-paste operations
+
+When copying an API key from one config file to another:
+
+1. Read both files as raw bytes/hex
+2. Confirm the destination key is byte-identical to the source key
+3. The display layer may **redact** keys with `...` — the raw file contains the real key. Don't copy the displayed version.
+4. Use `repr()` or hex dump to compare, not visual inspection of the truncated display
+
+## Gateway restart in single-process environments
+
+When Hermes runs as a single systemd service (gateway mode), you cannot restart it from within itself. Use these workarounds:
+
+```bash
+# Via busctl (works without spawning a second process)
+XDG_RUNTIME_DIR=/run/user/0 busctl call --user org.freedesktop.systemd1 \
+  /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager \
+  RestartUnit 'ss' '<service>.service' 'replace'
+
+# For profile-specific gateways (e.g., Anita profile):
+KY_PROFILE=anita
+service_name="hermes-gateway-$KY_PROFILE"
+XDG_RUNTIME_DIR=/run/user/0 busctl call --user org.freedesktop.systemd1 \
+  /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager \
+  StartUnit 'ss' "$service_name.service" 'replace'
+```