# Agent Discipline: Config Verification

This reference captures hard lessons about agent behavior with configuration.

## Rule

**Never set a configuration key unless you have verified it exists in the application's documentation, schema, or known-good examples.**

If you *assume* a config key exists and write it to a production config file:

1. The application silently ignores it (at best) or crashes (at worst)
2. The user's intent is not met
3. The agent appears to have fixed the problem when nothing actually changed
4. The bad key pollutes the config file and wastes debugging time later

## Examples of past violations

- `fallback_providers` — invented, does not exist in Hermes Agent config schema. The real behavior (manual provider switch) was never configured.

## Config file corruption during Python editing

Python scripts that read, search/replace, and write YAML config files can **corrupt the file structure** if the replacement logic is wrong (wrong old_string, partial match, or mismatched indentation). This causes Hermes to fail silently or crash on restart.

**This session's example:** Replacing `api_key: sk-lbh...bWPA` in the anita profile config (literally the string `sk-lbh...bWPA` with the dots) overwrote the real key value with the literal characters `sk-lbh...bWPA`, causing `HTTP 401: Authentication Error` every time Anita's gateway tried to authenticate against admin-ai.

**Rule:** Never use the *displayed/redacted* version of a credential in a search-and-replace operation. The redacted value shown in a `read_file` response (e.g. `sk-lbh...bWPA`) is NOT the real value — the dots are literal characters in the edit buffer but represent truncated content on disk. Always extract the raw value from a hex dump, raw bytes, or the original source file.

**Preferred workflow for credential fixing:**

```bash
# Step 1: Get the exact raw key bytes from the source
python3 -c "
with open('/root/.hermes/config.yaml', 'rb') as f:
    for line in f:
        if b'api_key:' in line and b'vision' not in line:
            print(line.hex())
"
# Step 2: Decode hex to verify the real string
echo '736b2d6c626868...' | xxd -r -p
# Step 3: Write the raw string to the target file
python3 -c "
with open('/root/.hermes/profiles/anita/config.yaml') as f:
    content = f.read()
content = content.replace('api_key: VERIFIED_BAD_VALUE', 'api_key: REAL_VALUE')
with open('/root/.hermes/profiles/anita/config.yaml', 'w') as f:
    f.write(content)
"
```

**Alternative:** Write the entire file fresh using `write_file` instead of search/replace — less error-prone for small config files.

## When a mistake happens

- Acknowledge it immediately
- Remove the bad config key
- Document what the actual approach should be
- Do not repeat the same assumption in the same session or on the same application
