Add WebSocket protocol docs + agent connection research

WEBSOCKET-PROTOCOL.md

@@ -0,0 +1,124 @@
+# Team Board WebSocket Protocol
+
+## Подключение
+
+```
+ws://localhost:8100/ws?client_type={type}&client_id={id}
+```
+
+- `client_type`: `human` | `agent` | `bridge`
+- `client_id`: уникальный идентификатор клиента (slug агента, имя bridge и т.д.)
+
+## Формат сообщений
+
+Все сообщения — JSON с полем `event`:
+
+```json
+{"event": "event.name", ...payload}
+```
+
+## События: Клиент → Сервер
+
+### auth
+Аутентификация (для агентов/bridge).
+```json
+{"event": "auth", "token": "agent-xxx"}
+```
+Ответ: `auth.ok` с `{"init": {}}`
+
+### chat.subscribe
+Подписка на чат-комнату.
+```json
+{"event": "chat.subscribe", "chat_id": "uuid"}
+```
+Ответ: `chat.subscribed`
+
+### chat.unsubscribe
+Отписка от чата.
+```json
+{"event": "chat.unsubscribe", "chat_id": "uuid"}
+```
+
+### chat.send
+Отправка сообщения в чат.
+```json
+{
+  "event": "chat.send",
+  "chat_id": "uuid",
+  "content": "текст сообщения",
+  "sender_type": "human|agent|system|bridge",
+  "sender_id": "optional-uuid",
+  "sender_name": "Имя отправителя"
+}
+```
+Сообщение сохраняется в БД и broadcast'ится всем подписчикам чата.
+
+### agent.heartbeat
+Пинг от агента (статус).
+```json
+{"event": "agent.heartbeat", "status": "idle|busy"}
+```
+Ответ: `agent.heartbeat.ack`
+
+## События: Сервер → Клиент
+
+### auth.ok
+```json
+{"event": "auth.ok", "init": {}}
+```
+
+### chat.subscribed
+```json
+{"event": "chat.subscribed", "chat_id": "uuid"}
+```
+
+### chat.message
+Новое сообщение в чате (broadcast всем подписчикам).
+```json
+{
+  "event": "chat.message",
+  "id": "msg-uuid",
+  "chat_id": "uuid",
+  "sender_type": "human|agent|system|bridge",
+  "sender_id": "uuid|null",
+  "sender_name": "Имя",
+  "content": "текст",
+  "created_at": "2026-02-20T12:00:00Z"
+}
+```
+
+### error
+```json
+{"event": "error", "message": "описание ошибки"}
+```
+
+## Чаты
+
+- **Lobby**: общий чат, ID: `25c20eaa-fbf1-4259-8501-0854cc926d0d`
+- **Project chat**: чат проекта (один на проект)
+- **Task chat**: чат задачи (один на задачу)
+
+### REST API для чатов
+```
+GET  /api/v1/chats/lobby              — получить lobby
+GET  /api/v1/chats/{id}/messages      — история сообщений
+POST /api/v1/chats/{id}/messages      — отправить (без WS)
+```
+
+## Telegram Bridge (планируется)
+
+Bridge-клиент подключается как `client_type=bridge`, подписывается на нужные чаты и:
+
+1. **Tracker → Telegram**: получает `chat.message`, форматирует и отправляет в Telegram группу
+2. **Telegram → Tracker**: получает сообщения из Telegram, отправляет `chat.send` с `sender_type=bridge`
+3. **Системные события**: статус задачи, новая задача и т.д.
+4. **Теги агентов**: парсит `@slug` в сообщениях из Telegram
+
+### Формат сообщений в Telegram
+```
+[Имя Агента] Текст сообщения
+```
+или
+```
+🤖 Кодер: Задача выполнена, коммит abc123
+```