feat: finalize matrix platform audit and docs

.planning/threads/matrix-file-ingestion-context.md

@@ -0,0 +1,81 @@
+# Thread: Matrix file ingestion and agent-visible storage contract
+
+## Status: IN PROGRESS
+
+## Goal
+
+Сохранить текущий контекст сессии для следующего агента и зафиксировать следующую архитектурную развилку: как принимать вложения из Matrix и делать их доступными агенту.
+
+## Current State
+
+Phase 4 Matrix MVP уже собран и проверен на уровне per-room routing:
+- обычные сообщения теперь идут в `platform_chat_id`, а не в общий локальный `C1/C2`
+- `!context` показывает состояние текущего Matrix-чата
+- `!save` и `!load` привязаны к текущему room-context
+- `PrototypeStateStore` хранит live state per context
+- последние изменения закоммичены в `feat/matrix-direct-agent-prototype`
+
+Коммиты, которые важно знать:
+- `c11c8ec` `feat(task-5): scope matrix context state per room`
+- `07c5078` `feat(task-7): verify matrix per-room context routing`
+
+## What We Learned About Platform Runtime
+
+Текущий `external/platform-agent` не является отдельным контейнером на чат.
+Фактическая модель сейчас такая:
+- один FastAPI-процесс
+- singleton `AgentService`
+- `thread_id` используется как ключ памяти в LangGraph, а не как контейнерная изоляция
+- файловой изоляции на чат сейчас нет
+- `/workspace` как общий mount для Matrix bot и platform-agent сейчас не настроен
+- отдельного upload API для вложений в текущем коде не видно
+
+Ключевые файлы:
+- `external/platform-agent/src/api/external.py`
+- `external/platform-agent/src/agent/service.py`
+- `external/platform-agent/src/agent/base.py`
+
+## File Handling Requirement
+
+Пользовательский запрос на текущем этапе:
+- принимать файл или сообщение с файлом из Matrix
+- сохранять файл локально
+- передавать агенту явный сигнал, что к сообщению есть вложения
+- сообщать, где лежит файл
+
+Но есть техническое ограничение:
+- если Matrix bot пишет файл только в своём контейнере, platform-agent его не увидит
+- значит нужен либо общий storage, либо upload в платформу, либо контейнеризация platform-agent с общим volume
+
+## Recommended Design Direction
+
+Самый прагматичный MVP-вариант:
+- хранить вложения в общем каталоге, который виден и Matrix bot, и platform-agent
+- формировать для агента структурированный payload с:
+  - локальным путём
+  - original filename
+  - mime type
+  - attachment type
+- если есть текст пользователя, дополнять сообщение краткой summary-подсказкой про вложения
+- если прислан только файл, отправлять synthetic message вроде “пользователь прислал файл”
+
+Если общий каталог невозможен в текущем runtime:
+- следующий вариант это upload endpoint в platform-agent
+- Matrix surface скачивает файл и загружает его в платформу, а платформа уже кладёт его в своё доступное хранилище
+
+## Open Questions
+
+1. Где должен жить shared storage: host path, docker volume или platform-side volume?
+2. Нужен ли немедленный upload API в platform-agent, или сначала достаточно shared path?
+3. Должны ли файлы быть scoped per room/platform_chat_id, а не per user?
+
+## Next Step For Another Agent
+
+1. Подтвердить runtime-модель хранения файлов.
+2. Проверить, как сейчас запускаются Matrix bot и platform-agent в реальной dev-схеме.
+3. После выбора storage contract начать с изменений в Matrix attachment ingestion.
+
+## Notes
+
+- Контекст этой сессии сохранён как отдельный thread, потому что текущий следующий рискованный шаг уже не про context routing, а про файловый transport.
+- Не смешивать этот трек с незавершённой историей про `!branch`: upstream branch/snapshot API всё ещё не подтверждён.