From 0aa103bd555046c076f944a35b83405ae83a6628 Mon Sep 17 00:00:00 2001
From: Alexey Martemyanov <mallexxx@gmail.com>
Date: Mon, 15 Jun 2026 10:36:16 +0600
Subject: [PATCH] [2026-06-15] add balda-valera how-to

---
 family/how-to/balda-valera.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 family/how-to/balda-valera.md

diff --git a/family/how-to/balda-valera.md b/family/how-to/balda-valera.md
new file mode 100644
index 00000000..63d71cbc
--- /dev/null
+++ b/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
+```