# Hermes Local Model Registration

## Pitfall: `hermes config set` fails on nested custom_providers

The `hermes config set` command cannot handle named keys inside list structures. Any attempt like:

```bash
hermes config set custom_providers.local.name "Local LLM"
```

Fails with:
```
TypeError: Cannot navigate into list at key 'custom_providers.local.name': segment 'local' is not a numeric index
```

This is because `custom_providers` is a YAML list (not a dict), and Hermes expects numeric indices like `custom_providers.0.name`.

## Solution: Direct YAML manipulation

Use Python to read, modify, and write the config:

```python
import yaml

# Read
with open('/home/rurouni/.hermes/config.yaml') as f:
    config = yaml.safe_load(f)

# Add custom_providers (always back up first!)
config['custom_providers'] = [{
    'name': 'Local LLM',
    'base_url': 'http://127.0.0.1:8081/v1',
    'api_key_env': '',
    'models': [
        {
            'id': 'local-model-id',
            'name': 'Display Name',
            'context_length': 200000,
            'description': 'Description shown in /model picker'
        },
        # ... more models
    ]
}]

# Set defaults
config['model']['provider'] = 'custom:local'
config['model']['default'] = 'local-model-id'
config['model']['base_url'] = 'http://127.0.0.1:8081/v1'

# Backup
import shutil, time
shutil.copy('/home/rurouni/.hermes/config.yaml',
            f'/home/rurouni/.hermes/config.yaml.bak-{time.strftime("%Y%m%d-%H%M%S")}')

# Write
with open('/home/rurouni/.hermes/config.yaml', 'w') as f:
    yaml.dump(config, f, default_flow_style=False, sort_keys=False, allow_unicode=True, width=200)

# Verify
print("Valid YAML ✓" if yaml.safe_load(open('/home/rurouni/.hermes/config.yaml')) else "FAIL")
```

## Model ID Convention

Use lowercase, hyphenated IDs matching the format:
```
local-<model>-<quant>
```

Examples:
- `local-qwen3.6-35b-heretic-mtp-q4km`
- `local-qwen3.5-9b-deepseek-flash-mtp-q6k`

## Model Registration Checklist

After adding models to config.yaml:
1. Verify with `python3 -c "import yaml; c=yaml.safe_load(open('~/.hermes/config.yaml')); print(c['custom_providers'][0]['models'])"`
2. Restart gateway: `hermes gateway restart`
3. Test with `/model` slash command in chat
4. If models don't appear: check that `custom_providers[0].base_url` is valid (empty URL silently drops the provider)