docs: add platform integration guide to README

README.md

@@ -2,6 +2,46 @@
 
 Matrix-бот для взаимодействия пользователя с AI-агентом Lambda.
 
+## Интеграция для платформы
+
+Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами.
+
+### Что бот ожидает от вас
+
+**1. HTTP-эндпоинт агента**
+Бот подключается к агенту через `lambda_agent_api.AgentApi` по адресу `AGENT_BASE_URL`.
+Протокол — WebSocket поверх HTTP, контракт описан в `docs/deploy-architecture.md`.
+
+**2. Shared volume**
+Бот пишет файлы пользователей в Docker volume, смонтированный как `/agents`.
+Агент должен видеть тот же volume — как `/workspace`.
+
+```
+Bot container          Agent container
+  /agents/   ←──── named Docker volume ────→  /workspace/
+```
+
+Бот кладёт входящие файлы по пути `surfaces/matrix/{user}/{room}/inbox/{file}` и передаёт агенту этот относительный путь. Исходящие файлы агент пишет в свой `/workspace/`, бот читает их оттуда же.
+
+**3. Конфиг агентов**
+Файл `config/matrix-agents.yaml` — маппинг Matrix-пользователей на агентов. Вы заполняете его под свою инфраструктуру. Пример в `config/matrix-agents.example.yaml`.
+
+### Что бот не делает
+
+- Не управляет lifecycle агент-контейнеров (запуск/остановка — на вашей стороне)
+- Не хранит историю разговоров (это в памяти агента)
+- Не обрабатывает аутентификацию пользователей — любой Matrix-пользователь, который пишет боту, получает доступ
+
+### Минимальный чеклист
+
+- [ ] Заполнить `.env` (по шаблону `.env.example`)
+- [ ] Заполнить `config/matrix-agents.yaml` (ID агентов и маппинг пользователей)
+- [ ] Убедиться что `AGENT_BASE_URL` доступен из контейнера бота
+- [ ] Смонтировать один и тот же named volume в бот (`/agents`) и в агент (`/workspace`)
+- [ ] Запустить: `docker compose -f docker-compose.prod.yml up -d --build`
+
+---
+
 ## Статус
 
 Matrix MVP готов к деплою. Telegram — в отдельном worktree, не входит в этот handoff.