docs: add Matrix Gateway integration report

- 9 rooms synced with Matrix successfully
- 16 rooms pending due to rate limiting
- Matrix Gateway endpoints working
- Auto-create logic implemented for agent/node/microdao chat rooms

docs/debug/matrix_gateway_integration_report_20251130.md

@@ -0,0 +1,124 @@
+# Matrix Gateway Integration — Звіт про виконання
+
+**Дата:** 2025-11-30
+**Статус:** ЧАСТКОВО ВИКОНАНО (rate limiting)
+
+## 1. Мета
+
+Інтегрувати Matrix Gateway з City Service для створення реальних Matrix кімнат.
+
+## 2. Виконані роботи
+
+### 2.1. Matrix Gateway — Нові endpoints ✅
+
+```
+POST /internal/matrix/room/join     - Join user to room
+POST /internal/matrix/message/send  - Send message to room
+GET  /internal/matrix/rooms/{id}/messages - Get room messages
+```
+
+### 2.2. City Service — Matrix Client ✅
+
+Нові функції в `matrix_client.py`:
+- `join_user_to_room(room_id, user_id)`
+- `send_message_to_room(room_id, body, sender)`
+- `get_room_messages(room_id, limit)`
+- `ensure_room_has_matrix(room_slug, room_name, visibility)`
+
+### 2.3. City Service — Room Sync ✅
+
+```
+POST /city/rooms/sync/matrix - Bulk sync rooms with Matrix
+```
+
+### 2.4. Auto-create Matrix Rooms ✅
+
+Оновлені endpoints автоматично створюють Matrix кімнати:
+- `GET /api/v1/agents/{id}/chat-room`
+- `GET /api/v1/nodes/{id}/chat-room`
+- `GET /api/v1/microdaos/{slug}/chat-room`
+
+## 3. Результати синхронізації
+
+### Перший запуск:
+- **Total rooms:** 25
+- **Synced:** 9 (з Matrix room_id)
+- **Failed:** 16 (rate limiting)
+
+### Успішно синхронізовані:
+| Room Slug | Matrix Room ID |
+|-----------|----------------|
+| energy | !gykdLyazhkcSZGHmbG:daarion.space |
+| science | !enYcpGlcPfCuWEIwjv:daarion.space |
+| builders | !VdxezYlgrmNTFVkNUk:daarion.space |
+| general | !anDoaSvRxICMHLkeqg:daarion.space |
+| welcome | !YbacjkzhdDjaOXgxTy:daarion.space |
+| web3-district | !EBOtJRwWKYgdYzcZla:daarion.space |
+| leadership-hall | !zFinGbbbMykYULmIOv:daarion.space |
+| vision-studio | !HzNtIvobAgaoDBpPpD:daarion.space |
+| rnd-lab | !exvkRpdsvZlWjaUfmV:daarion.space |
+
+### Не синхронізовані (rate limiting):
+- economics-square
+- announcements
+- science-lab
+- security-bureau
+- daarion-news, daarion-builders, daarion-help, daarion-governance
+- node-support-node1, node-support-node2
+- memory-vault, security-bunker, system-control, engineering-lab, marketing-hub, finance-office
+
+## 4. Проблеми
+
+### 4.1. Matrix Rate Limiting
+
+```
+{"errcode":"M_LIMIT_EXCEEDED","error":"Too Many Requests","retry_after_ms":55397}
+```
+
+**Причина:** Synapse має rate limiting для створення кімнат.
+
+**Рішення:**
+1. Почекати `retry_after_ms` і повторити
+2. Налаштувати Synapse `rc_message` та `rc_admin` в `homeserver.yaml`
+3. Додати затримку між створенням кімнат в sync endpoint
+
+### 4.2. Agent Chat Rooms
+
+Agent console rooms (`agent-console-*`) не мають Matrix ID через rate limiting.
+
+**Рішення:** Повторити sync пізніше або створити вручну.
+
+## 5. Перевірка на DAARION.space
+
+| Endpoint | Статус | Примітки |
+|----------|--------|----------|
+| Matrix Gateway `/healthz` | ✅ | `{"status":"ok","synapse":"connected"}` |
+| `/city/rooms/sync/matrix` | ✅ | Працює, але rate limited |
+| `/api/v1/agents/{id}/chat-room` | ⚠️ | Створює DB room, Matrix pending |
+| `/api/v1/nodes/{id}/chat-room` | ⚠️ | Створює DB room, Matrix pending |
+| `/api/v1/microdaos/{slug}/chat-room` | ⚠️ | Створює DB room, Matrix pending |
+
+## 6. Наступні кроки
+
+1. **Налаштувати Synapse rate limiting** — збільшити ліміти для admin user
+2. **Повторити sync** — через 5-10 хвилин
+3. **Додати retry logic** — в sync endpoint
+4. **Перевірити chat widget** — після створення Matrix rooms
+
+## 7. SQL Queries для перевірки
+
+```sql
+-- Rooms з Matrix ID
+SELECT slug, name, matrix_room_id FROM city_rooms 
+WHERE matrix_room_id IS NOT NULL;
+
+-- Rooms без Matrix ID
+SELECT slug, name FROM city_rooms 
+WHERE matrix_room_id IS NULL;
+```
+
+---
+
+**Автор:** Cursor AI
+**Таск:** `TASK_PHASE_MATRIX_GATEWAY_INTEGRATION_v1.md`
+