# RUNBOOK — Bifrost VK OpenCode Fix + Veille Fallback

**Date** : 2026-06-23  
**Contexte** : Veille bolbol.tn — "Resume indisponible" systematique

## Symptomes

- `00:00` et `19:00` : `could not auto resolve a provider`
- `07:00` : `GoUsageLimitError — Weekly usage limit reached`

## Diagnostic

### Erreur 1 — could not auto resolve
Node n8n `Enrichir via Bifrost` (workflow 9378593adccf42dc) envoie x-bf-vk: bfk-e5832bfe (Nabil-Key), model: deepseek-v4-flash.
La Nabil-Key VK n'avait pas OpenCode dans governance_virtual_key_provider_configs.
Bifrost cherchait deepseek-v4-flash dans openrouter/google/nvidia_nim -> introuvable.

### Erreur 2 — GoUsageLimitError
Job cron hermes-nyora `veille-hebdo-nexum-kanban-a1b2c3d4` avait model/provider null.
Orchestrateur -> provider par defaut = OpenCode Go direct -> quota hebdo epuise lundi.
NOTE: Les 6 workers kanban utilisent le profil veilleur (openrouter) -> OK. Seul l'orchestrateur est affecte.

## Fixes appliques

### Fix 1 — Bifrost DB: OpenCode ajoute a Nabil-Key VK
```python
conn = sqlite3.connect('/mnt/docker/bifrost/data/config.db')
cur = conn.cursor()
vk = 'dc17fe0c-f7bf-4752-acb8-798156b2ec9e'
models = '["deepseek-v4-flash","deepseek-v4-pro","glm-5.1","kimi-k2.6"]'
cur.execute(
    "INSERT INTO governance_virtual_key_provider_configs "
    "(virtual_key_id, provider, weight, allowed_models, blacklisted_models, allow_all_keys) "
    "VALUES (?, 'opencode', 1.0, ?, '[]', 1)", (vk, models))
conn.commit()
```

### Fix 2 — Bifrost DB: OpenCode key persistee dans config_keys
```python
kid = str(uuid.uuid4())
now = datetime.datetime.utcnow().isoformat() + 'Z'
cur.execute(
    "INSERT INTO config_keys (name,provider_id,provider,key_id,value,models_json,"
    "blacklisted_models_json,weight,enabled,encryption_status,created_at,updated_at) "
    "VALUES ('opencode-1',36,'opencode',?,?,?,'[]',1.0,1,'plain_text',?,?)",
    (kid, BIFROST_OPENCODE_KEY, models, now, now))
conn.commit()
```

### Fix 3 — Bifrost restart (requis apres modif DB)
Via Portainer API http://172.17.0.1:9000 (endpoint_id=2, container 3136d565d6dd).
Auth: POST /api/auth -> jwt. Actions: stop + start sur /api/endpoints/2/docker/containers/{id}/{action}
ATTENTION: container ID change apres recreate -> verifier avant.

### Fix 4 — jobs.json hermes-nyora: orchestrateur job 2
Fichier: /mnt/docker/hermes-platform/hermes-nyora/data/cron/jobs.json
Job veille-hebdo-nexum-kanban-a1b2c3d4 -> model: deepseek/deepseek-v4-flash, provider: openrouter

### Fix 5 — n8n workflow 9378593adccf42dc: fallback gemini-2.5-flash
Node Enrichir via Bifrost modifie: si GoUsageLimitError -> retry avec gemini-2.5-flash.
Via n8n API: PUT /api/v1/workflows/9378593adccf42dc avec {name, nodes, connections, settings}.

## Architecture finale (VK Nabil-Key bfk-e5832bfe)

| Provider    | Modeles autorises                                                      |
|-------------|------------------------------------------------------------------------|
| openrouter  | Gemma-4-31B/26B free, Nemotron, GPT-OSS free, Hermes-3, Qwen3-coder  |
| google      | gemma-4-31b/26b, gemini-2.5-flash, gemini-2.5-flash-lite              |
| nvidia_nim  | Llama-3.3-70B, Nemotron-70B, Llama-405B, Qwen2.5-Coder                |
| opencode    | deepseek-v4-flash, deepseek-v4-pro, glm-5.1, kimi-k2.6 (NOUVEAU)     |

## Pieges a eviter

- Bifrost ne hot-reload PAS les providers -> restart obligatoire apres modif DB
- config.json charge providers au boot en memoire; config_keys DB = source persistante
- auth Bifrost = x-bf-vk header, PAS Authorization: Bearer -> 401
- Portainer container ID change apres recreate -> verifier avant restart
- N8N PUT /workflows: accepte uniquement {name, nodes, connections, settings} -> 400 sinon

## MCP NAS — Regles de scripting fiables

| NE PAS faire                               | Faire a la place                              |
|--------------------------------------------|-----------------------------------------------|
| Heredoc << 'EOF'                           | Base64 encode -> transfer -> decode           |
| printf 'long code python' | python3 >400c  | printf > /tmp/s.py && python3 /tmp/s.py       |
| Commands dans session apres plusieurs err  | Nouvelle session ou session differente        |
| Pipes complexes inline dans printf         | Script intermediaire en /tmp/                 |