From 7668508911ece9aa2612d47ec434d31479bbe729 Mon Sep 17 00:00:00 2001
From: Alexey Martemyanov <mallexxx@gmail.com>
Date: Tue, 16 Jun 2026 13:12:59 +0600
Subject: [PATCH] [2026-06-16] balda: sync docs with disabled events polling;
 add zulip-router bot creation guide

---
 personal/projects/balda/balda-valera.md    | 18 +++++++--------
 personal/projects/balda/claudio-klaudiy.md |  6 ++---
 personal/projects/zulip-router.md          | 27 ++++++++++++++++++----
 3 files changed, 35 insertions(+), 16 deletions(-)

diff --git a/personal/projects/balda/balda-valera.md b/personal/projects/balda/balda-valera.md
index 182b015c..88521785 100644
--- a/personal/projects/balda/balda-valera.md
+++ b/personal/projects/balda/balda-valera.md
@@ -19,24 +19,24 @@ docker-compose build && docker-compose up -d
 ## Архитектура получения сообщений
 Валера — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.
 
-Для получения всех сообщений в теме — Events API polling (горутина в коде):
-- `events_polling.enabled: true` в config.yaml
-- Очередь регистрируется с `all_public_streams=true`
-- Бот подписывается на все публичные стримы при старте (`SubscribeToPublicStreams`)
+Для получения всех сообщений в теме — **Events API polling** (отключён, после деплоя zulip-router будет удалён из кода):
+- `events_polling.enabled: false` в config.yaml (текущее состояние)
+- Сообщения приходят только через **outgoing webhook** (webhook_token в .env)
 - После @mention создаётся сессия; последующие сообщения без @mention обрабатываются
 
 **После перезапуска**: нужно один раз написать `@Валера <текст>` чтобы создать сессию в теме.
 
 ## Диагностика молчания
 1. Проверить логи: `docker logs balda-agent-valera-1 --tail 50`
-2. Проверить что Events API polling запустился: `zulip events queue registered` в логах
+2. Проверить что бот запущен и webhook слушает: в логах `zulip webhook server starting addr=0.0.0.0:8091`
 3. Стухший NATS-таск (симптом: логов нет после @mention)  
    Фикс: `docker-compose restart` (NATS embedded, состояние в памяти)
-4. Бот не подписан на стримы (симптом: `processing zulip message trigger=stream` не появляется):
+4. Проверить webhook со стороны: отправить POST с curl:
    ```bash
-   curl -u "<bot_email>:<api_key>" https://zulip.qentra.top/api/v1/users/me/subscriptions
+   curl -X POST http://localhost:8091/zulip/webhook \
+     -H "Content-Type: application/json" \
+     -d '{"type":"test"}'
    ```
-   Если пустой — должен подписаться при следующем старте. Или вручную через API.
 
 ## Патчи в коде (общие с Клавдием)
 
@@ -82,7 +82,7 @@ balda:
   provider: deepseek
   zulip:
     events_polling:
-      enabled: true
+      enabled: false          # true → если events polling нужен (сейчас отключён)
     stream_only_with_session: true
 runtime:
   providers:
diff --git a/personal/projects/balda/claudio-klaudiy.md b/personal/projects/balda/claudio-klaudiy.md
index 06b043a0..e1933333 100644
--- a/personal/projects/balda/claudio-klaudiy.md
+++ b/personal/projects/balda/claudio-klaudiy.md
@@ -22,9 +22,9 @@ docker-compose build && docker-compose up -d  # после изменений в
 
 Клавдий — **outgoing webhook bot** (bot_type=3). Zulip отправляет webhook только для @mention и DM.
 
-Для получения всех сообщений в теме — **Events API polling**:
-- Подписан на все публичные стримы при старте
-- После @mention создаётся сессия; последующие сообщения без @mention обрабатываются
+Для получения всех сообщений в теме — **Events API polling** (отключён, после деплоя zulip-router будет удалён из кода):
+- `events_polling.enabled: false` в config.yaml (текущее состояние)
+- Сообщения приходят только через **outgoing webhook**
 
 ## Отличие от Валеры
 
diff --git a/personal/projects/zulip-router.md b/personal/projects/zulip-router.md
index f47a41c7..f6a86cee 100644
--- a/personal/projects/zulip-router.md
+++ b/personal/projects/zulip-router.md
@@ -75,16 +75,35 @@ zulip:
 
 **Compose:** `~/Docker/zulip-router/docker-compose.yaml`
 
-**Env vars:**
+### Перед запуском: создать бота-роутера в Zulip
+
+Нужен **отдельный** бот (не valera-bot, не claudio-bot).
+
+1. В Zulip: **Settings → Bots → Add a new bot**
+2. Тип: **Outgoing webhook**
+3. Имя: `zulip-router` (или любое)
+4. Bot email: скопировать (понадобится в .env)
+5. API key: скопировать (понадобится в .env)
+6. Endpoint URL: не заполнять (роутер сам поллит, webhook от Zulip ему не нужен)
+7. Сохранить
+
+### Env vars
+
+Создать `~/Docker/zulip-router/.env`:
 ```env
-ZULIP_ROUTER_API_KEY=<api-key бота-роутера>
+ZULIP_ROUTER_BOT_EMAIL=zulip-router-bot@zulip.qentra.top
+ZULIP_ROUTER_API_KEY=<api-key из шага 5>
+
+# Куда форвардить
+VALERA_WEBHOOK=http://balda-agent-valera-1:8091/zulip/webhook
+CLAUDIO_WEBHOOK=http://claudio-agent-claudio-1:8092/zulip/webhook
 ```
 
-**Запуск:**
+### Запуск
 ```bash
 cd ~/Docker/zulip-router
 docker-compose up -d
-```
+docker logs zulip-router --tail 20   # проверить что poll loop запущен
 
 ## TODO