From b3331464d9440404acd37ed936a8b37de85fe440 Mon Sep 17 00:00:00 2001
From: Mikhail Putilovskij <mputilovskij@gmail.com>
Date: Sun, 19 Apr 2026 21:06:03 +0300
Subject: [PATCH] docs: update README with Matrix MVP runbook and feature
 status

Add step-by-step setup for running Matrix surface with real platform-agent,
document all available commands, and clearly list what works vs what is
blocked (StateBackend cross-chat load, hardcoded tokens, missing /reset,
no file upload API).
---
 README.md | 126 ++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 98 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index b2f69fb..e44f0cd 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,10 @@
 
 ## Статус
 
-Прототип в разработке. Matrix-адаптер по умолчанию работает через `MockPlatformClient`, но может переключаться на реальный direct-agent backend через `MATRIX_PLATFORM_BACKEND=real`.
-
-| Поверхность | Статус | Описание |
-|---|---|---|
-| Telegram | 🔨 В разработке | DM + Forum Topics mode, активная реализация сейчас в отдельном worktree |
-| Matrix | 🔨 В разработке | Незашифрованные комнаты: бот создаёт private Space и отдельную room на каждый чат |
+| Поверхность | Статус |
+|---|---|
+| Telegram | 🔨 В разработке, отдельный worktree `feat/telegram-adapter` |
+| Matrix | ✅ Рабочий прототип, подключается к реальному агенту |
 
 ---
 
@@ -96,40 +94,112 @@ class PlatformClient(Protocol):
 
 ---
 
-## Быстрый старт
+## Запуск Matrix-поверхности
+
+### 1. Зависимости и тесты
 
 ```bash
-# Зависимости
-uv sync   # или: pip install -e ".[dev]"
-
-# Тесты
+uv sync
 pytest tests/ -v
+```
+
+### 2. Переменные окружения
+
+```bash
+cp .env.example .env
+```
+
+Обязательные переменные:
+
+```env
+# Matrix аккаунт бота
+MATRIX_HOMESERVER=https://matrix.example.org
+MATRIX_USER_ID=@lambda-bot:example.org
+MATRIX_PASSWORD=...           # или MATRIX_ACCESS_TOKEN=...
+
+# Выбор backend: mock (по умолчанию) или real (подключение к platform-agent)
+MATRIX_PLATFORM_BACKEND=real
+
+# URL WebSocket endpoint platform-agent (только при MATRIX_PLATFORM_BACKEND=real)
+AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/
+AGENT_BASE_URL=http://127.0.0.1:8000
+```
+
+### 3. Запуск platform-agent (для real backend)
+
+platform-agent — отдельный репозиторий, сейчас клонируется в `external/platform-agent`.
+
+```bash
+cd external/platform-agent
+
+# Создать .env с параметрами LLM провайдера
+cat > .env <<EOF
+PROVIDER_MODEL=openai/gpt-4o-mini
+PROVIDER_URL=https://openrouter.ai/api/v1
+PROVIDER_API_KEY=sk-or-...
+EOF
+
+# Запустить
+uv run uvicorn src.main:app --host 127.0.0.1 --port 8000
+```
+
+Проверить что работает: `curl http://127.0.0.1:8000/agent_ws/` должен вернуть ответ об апгрейде до WebSocket.
+
+### 4. Запуск бота
+
+```bash
+# Первый запуск или сброс состояния
+rm -f lambda_matrix.db && rm -rf matrix_store
 
-# Запустить Matrix бота
-cp .env.example .env  # заполнить MATRIX_* переменные
 PYTHONPATH=. uv run python -m adapter.matrix.bot
 ```
 
-### Telegram worktree
+### 5. Онбординг пользователя
 
-Текущая Telegram-разработка идёт в отдельном worktree:
+Пригласи Matrix-аккаунт бота в личный DM. Бот создаст:
+- Private Space `Lambda — {имя}`
+- Рабочую комнату `Чат 1` и пригласит туда
 
-```bash
-cd .worktrees/telegram
-export BOT_TOKEN=...
-PYTHONPATH=. python -m adapter.telegram.bot
-```
+Дальнейшее общение ведётся в рабочей комнате.
 
-### Matrix manual QA
+---
 
-Пока Matrix-бот тестируется в незашифрованных комнатах:
+## Функционал Matrix MVP
 
-```bash
-cd /path/to/surfaces-bot
-rm -f lambda_matrix.db
-rm -rf matrix_store
-PYTHONPATH=. uv run python -m adapter.matrix.bot
-```
+### Работает
+
+| Функция | Команда | Примечание |
+|---|---|---|
+| Онбординг | *(автоматически при invite)* | Создаёт Space + рабочую комнату |
+| Новый чат | `!new` | Создаёт дополнительную комнату |
+| Список чатов | `!chats` | Активные чаты пользователя |
+| Переименование | `!rename <название>` | |
+| Архивация | `!archive` | |
+| Диалог с агентом | *(любое сообщение)* | Стриминг ответа через WebSocket |
+| Изоляция контекста | *(автоматически)* | Каждая комната — отдельный thread_id агента |
+| Сохранение контекста | `!save [имя]` | Агент сохраняет краткое резюме разговора |
+| Список сохранений | `!load` | Выбор по номеру |
+| Состояние контекста | `!context` | Текущая сессия и список сохранений |
+| Справка | `!help` | |
+| Подтверждения | `!yes` / `!no` | Для опасных действий |
+
+### Не работает — блокеры на стороне platform-agent
+
+| Функция | Почему не работает |
+|---|---|
+| `!load` в другом чате | platform-agent использует `StateBackend` — файлы живут в памяти отдельно для каждого `thread_id`. Файл, сохранённый в чате A, не виден в чате B. Фикс: переключить platform-agent на `FilesystemBackend` с общим хранилищем. |
+| Счётчик токенов в `!context` | platform-agent отдаёт `tokens_used=0` хардкодом в `MsgEventEnd`. Наш код перехватывает значение корректно. |
+| `!reset` | platform-agent не имеет endpoint `/reset`. Задокументировано в ТЗ к платформе. |
+| Файловые вложения | Нет API загрузки файлов в область видимости агента. ТЗ передано платформе. |
+| Персистентность между рестартами | platform-agent использует `MemorySaver` (in-memory). Все разговоры теряются при рестарте процесса. |
+| E2EE комнаты | `python-olm` не собирается на macOS/ARM. Ограничение инфраструктуры. |
+
+### Не работает — пока не реализовано нами
+
+| Функция | Статус |
+|---|---|
+| `!settings`, `!skills`, `!soul`, `!safety` | Заглушки MVP. Требуют готового SDK платформы. |
+| Вложения (изображения, документы) | Только текстовые сообщения в текущем MVP. |
 
 ---