docs: fix README for platform integration — per-agent routing, compose as template

README.md

@@ -37,11 +37,10 @@ Bot container                  Agent containers
 
 ### Минимальный чеклист
 
-- [ ] Заполнить `.env` (по шаблону `.env.example`)
+- [ ] Заполнить `config/matrix-agents.yaml` — ID агентов, `base_url` каждого, `workspace_path`, маппинг пользователей
-- [ ] Заполнить `config/matrix-agents.yaml` (ID агентов и маппинг пользователей)
+- [ ] Задать переменные окружения (см. `.env.example`): Matrix credentials, `MATRIX_PLATFORM_BACKEND=real`, `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`
-- [ ] Убедиться что `AGENT_BASE_URL` доступен из контейнера бота
+- [ ] Смонтировать в бот-контейнер shared volume как `/agents` — каждый агент должен видеть свою поддиректорию как `/workspace`
-- [ ] Смонтировать один и тот же named volume в бот (`/agents`) и в агент (`/workspace`)
+- [ ] Добавить бот-сервис в свой compose (используйте `docker-compose.prod.yml` как шаблон сервиса)
-- [ ] Запустить: `docker compose -f docker-compose.prod.yml up -d --build`
 
 ---
 
@@ -95,7 +94,7 @@ cp .env.example .env
 | `MATRIX_USER_ID` | ✓ | `@bot:example.org` |
 | `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) |
 | `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна |
-| `AGENT_BASE_URL` | ✓ | HTTP-URL агента, например `http://platform-agent:8000` |
+| `AGENT_BASE_URL` | | Fallback URL агента если `base_url` не задан в `matrix-agents.yaml` |
 | `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` |
 | `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) |
 | `SURFACES_SHARED_VOLUME` | | имя Docker volume (по умолчанию `surfaces-agents`) |
@@ -129,12 +128,13 @@ agents:
 
 ### Production (bot-only)
 
+`docker-compose.prod.yml` — шаблон сервиса `matrix-bot`. Платформа добавляет этот сервис в свой compose рядом с агент-контейнерами, монтирует shared volume и задаёт переменные окружения.
+
+Для изолированного запуска бота без агентов (smoke-тест):
 ```bash
 docker compose --env-file .env -f docker-compose.prod.yml up -d --build
 ```
 
-Поднимает только `matrix-bot`. Монтирует shared volume в `/agents`. Требует внешний `AGENT_BASE_URL`.
-
 ### Fullstack E2E (bot + agent)
 
 ```bash
@@ -154,11 +154,14 @@ rm -f lambda_matrix.db && rm -rf matrix_store
 ## Shared volume: передача файлов
 
 ```
-Bot (/agents)                       Agent (/workspace)
+Bot (/agents)              Agent (/workspace = /agents/N/)
-  └── surfaces/matrix/{user}/{room}/inbox/file  ←── одно и то же хранилище
+  /agents/0/incoming/  ←──── одно и то же хранилище ────→  /workspace/incoming/
+  /agents/0/output/    ←────────────────────────────────→  /workspace/output/
 ```
 
-Бот пишет входящие файлы в `/agents/surfaces/matrix/{user}/{room}/inbox/{stamp}-{filename}` и передаёт агенту относительный путь. Исходящие файлы агент пишет в `/workspace/...`, бот читает из `/agents/...`.
+- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, передаёт агенту `attachments=["incoming/{stamp}-{file}"]`
+- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file` и отправляет пользователю как Matrix file message
+- `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml`
 
 ---