docs: clarify matrix file sending flow

README.md

@@ -156,6 +156,16 @@ Matrix бот подключается к `platform-agent` по service name, а
 Если Matrix-клиент отправляет файлы отдельными media events, бот не вызывает агента сразу.
 Вместо этого он сохраняет файлы в shared `/workspace`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения.
 
+Как отправить файлы агенту:
+
+1. Отправь один или несколько файлов в рабочую Matrix-комнату.
+2. При необходимости проверь очередь командой `!list`.
+3. Напиши обычное текстовое сообщение, например:
+   - `что на изображении?`
+   - `прочитай pdf и сделай summary`
+   - `сравни эти два файла`
+4. Это сообщение уйдёт агенту вместе со всеми staged файлами из очереди.
+
 Команды:
 
 - `!list` — показать staged вложения
@@ -164,6 +174,31 @@ Matrix бот подключается к `platform-agent` по service name, а
 
 Следующее обычное сообщение пользователя уходит агенту вместе со всеми staged файлами.
 
+Пример:
+
+```text
+[отправил 2 изображения]
+!list
+1. IMG_3183.png
+2. minion.jpeg
+
+что изображено на фото
+```
+
+В этом сценарии вопрос `что изображено на фото` будет отправлен агенту вместе с обоими файлами.
+
+Важно:
+
+- если после файлов отправить `!list` или `!remove`, агент не вызывается
+- если платформа вернула ошибку на этих вложениях, они остаются в staged-очереди
+- в таком случае следующее обычное сообщение снова попытается отправить те же файлы
+- чтобы разорвать этот цикл, используй `!remove <n>` или `!remove all`
+
+Известное ограничение текущего platform-agent:
+
+- большие изображения могут не пройти в provider из-за лимита на размер data URI
+- в таком случае Matrix-бот ответит `Сервис временно недоступен...`, а проблемные файлы останутся в очереди до явного удаления
+
 ### 5. Запуск бота вручную
 
 ```bash