[2026-06-15] add balda-valera how-to

family/how-to/balda-valera.md

@@ -0,0 +1,33 @@
+# Балда / Валера — эксплуатация
+
+## Расположение
+- Repo: `/Users/admin/Developer/balda/`
+- Compose: `compose.valera.yaml`
+- Config (persistent): `.config/balda/config.yaml`
+- Env: `.env`
+
+## Запуск / рестарт
+```
+cd /Users/admin/Developer/balda
+docker compose -f compose.valera.yaml restart
+```
+
+## Диагностика молчания
+1. Проверить логи: `docker logs balda-valera-1 --tail 50`
+2. Стухший NATS-таск → симптом: новые сообщения не порождают новые turn-ID  
+   Фикс: рестарт контейнера (NATS embedded, состояние в памяти)
+3. Неверный API endpoint → в логах: `"Incorrect API key / platform.openai.com"`  
+   Проверить config.yaml: `runtime.providers.deepseek.openai.base_url`  
+   Должно быть `https://api.deepseek.com/v1`
+
+## Конфигурация провайдера
+В `config.yaml` обязательно:
+```yaml
+balda:
+  provider: deepseek
+runtime:
+  providers:
+    deepseek:
+      openai:
+        base_url: https://api.deepseek.com/v1
+```