feat: finalize matrix platform audit and docs

.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md

@@ -3,11 +3,11 @@ phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow
 task: 1
 total_tasks: 2
 status: paused
-last_updated: 2026-04-07T15:11:42.203Z
+last_updated: 2026-04-07T21:29:48.982Z
 ---
 
 <current_state>
-Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`, which has not been implemented yet. Since the earlier checkpoint, a fresh live review of the platform repos confirmed that `master` still does not provide a usable consumer-facing control-plane API, but a working Matrix prototype is now feasible by talking directly to the `agent` WebSocket through a new `sdk/real.py` compatibility shim.
+Formally, the most recently active execution artifact inside the roadmap is still `01.1-03-PLAN.md`, which has not been implemented yet. In parallel, the platform-integration track has moved forward: the direct-agent Matrix prototype design is now approved, the implementation plan is written, and the next useful session should evaluate that spec/plan pair against the live platform repos before starting execution.
 </current_state>
 
 <completed_work>
@@ -16,16 +16,19 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 - Confirmed `master` is still only a thin HTTP skeleton with `/health` and `/users/{user_id}`, not a chat/session/settings backend for surfaces.
 - Confirmed `agent` exposes a working `/agent_ws/` WebSocket and `agent_api` provides enough protocol/client code to stream model output.
 - Identified the real technical gap for a prototype: `agent` currently uses a singleton service with a fixed `thread_id="default"`, so all conversations would share memory unless that is parameterized.
-- Derived the recommended prototype path: keep Matrix adapter logic largely intact, add a new `sdk/real.py` shim for direct agent communication, and ask the platform team for a minimal agent-side change to support per-chat thread identity.
-- Started a product/architecture discussion about where that prototype should live: in this repo as the first real backend path, or in a separate repo as a Matrix-only spike. The user asked to save the session before answering that design question.
+- Derived and got approval for the prototype path: keep Matrix adapter logic largely intact, add `sdk/agent_session.py`, `sdk/prototype_state.py`, and `sdk/real.py`, keep settings local, and use the direct `agent` WebSocket for real messaging.
+- Resolved the repo-placement question: the prototype stays in this repo on its own branch, not in a separate prototype repo.
+- Resolved the platform-change minimization question: prefer patching only `platform/agent`, not `platform/agent_api`, and use a tiny local WebSocket client in this repo.
+- Wrote and committed the approved design spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`.
+- Wrote the implementation plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </completed_work>
 
 <remaining_work>
 
 - Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests.
 - Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed.
-- Design follow-up: decide whether the direct-agent prototype belongs in this repo or a separate repo.
-- Future prototype work, once design is approved: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
+- Prototype evaluation follow-up: review the approved spec and plan against the platform repos before starting execution.
+- Future prototype work: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
 </remaining_work>
 
 <decisions_made>
@@ -34,6 +37,8 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 - Use the direct `agent` WebSocket as the only realistic path for a working prototype right now.
 - Keep consumer-facing Matrix logic as intact as possible and absorb backend differences inside a shim under `sdk/`.
 - Treat future platform evolution as likely to split into at least two concerns: control-plane access and direct agent session streaming.
+- Keep the prototype in this repo on its own branch.
+- Minimize platform-side changes by patching only `platform/agent` if possible.
 </decisions_made>
 
 <blockers>
@@ -43,12 +48,16 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 </blockers>
 
 <context>
-The important mental model changed slightly since the earlier checkpoint. Before, the conclusion was mainly “Phase 02 is blocked because the platform contract is unstable.” That is still true for full SDK integration through `master`, but it is no longer the whole story. There is now a practical bridge strategy: use the existing `agent` WebSocket directly for message generation, keep settings/user mapping local for the prototype, and preserve adapter stability by hiding all of this behind a new `sdk/real.py` implementation. The open architecture decision is repo placement: short-lived prototype repo versus building the first durable real-backend path here.
+The important mental model is now stable enough to execute. Full SDK integration through `master` is still premature, but a working Matrix prototype can be built now by talking directly to the `agent` WebSocket and hiding the split backend reality behind `sdk/real.py`. The approved design keeps the prototype in this repo, keeps settings local, and minimizes platform changes by preferring a tiny `platform/agent` patch over broader protocol churn. For evaluation and implementation context, inspect:
+- local spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`
+- local plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`
+- remote repos: `https://git.lambda.coredump.ru/platform/agent`, `https://git.lambda.coredump.ru/platform/master`, `https://git.lambda.coredump.ru/platform/agent_api`
+- local clones: `/tmp/platform-agent`, `/tmp/platform-master`, `/tmp/platform-agent_api`
 </context>
 
 <next_action>
 Resume with one of these depending on priority:
-1. If continuing phase execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
-2. If continuing platform design, answer the pending repo-placement question: keep the prototype in this repo or create a separate repo for a Matrix-only spike.
-3. After that decision, write the design for the direct-agent shim path before touching code.
+1. Evaluate the approved prototype spec and implementation plan against the live platform repos and decide whether to start in this repo or patch `platform/agent` first.
+2. If staying on roadmap execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
+3. If starting prototype execution immediately, begin with Task 1 of `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </next_action>

.planning/threads/matrix-dev-prototype-agent-platform-state.md

@@ -1,6 +1,6 @@
 # Thread: Matrix dev prototype — состояние агента и платформы
 
-## Status: OPEN
+## Status: IN PROGRESS
 
 ## Goal
 

.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 всё ещё не подтверждён.