# 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'
```