docs(05-04): document split deployment artifacts

- document prod vs fullstack compose usage
- align operator docs with shared /agents contract

README.md

@@ -7,7 +7,7 @@
 | Поверхность | Статус |
 |---|---|
 | Telegram | 🔨 В разработке, отдельный worktree `feat/telegram-adapter` |
-| Matrix | ✅ Рабочий прототип, запускается через root `docker compose` вместе с `platform-agent` |
+| Matrix | ✅ MVP runtime: `docker-compose.prod.yml` для bot-only handoff, `docker-compose.fullstack.yml` для internal E2E |
 
 ---
 
@@ -90,7 +90,7 @@ class PlatformClient(Protocol):
 Бот передаёт `user_id` + `chat_id` + сообщение; платформа сама решает нужно ли поднять контейнер.
 
 Сейчас: `MockPlatformClient` в `sdk/mock.py`, а Matrix real backend собирается через `sdk/real.py` при `MATRIX_PLATFORM_BACKEND=real`.
-Файловый контракт уже path-based: бот пишет файлы в shared `/workspace` и передаёт платформе относительные пути в `attachments`.
+Файловый контракт уже path-based: бот пишет файлы в shared `/agents` и передаёт платформе относительные пути в `attachments`, которые агент читает внутри своего `/workspace`.
 Когда SDK готов: добавляем `SdkPlatformClient`, меняем одну строку в DI. Адаптеры и ядро не трогаем.
 
 ---
@@ -121,9 +121,13 @@ MATRIX_PASSWORD=...           # или MATRIX_ACCESS_TOKEN=...
 # Выбор backend: mock (по умолчанию) или real (подключение к platform-agent)
 MATRIX_PLATFORM_BACKEND=real
 
-# compose runtime: platform-agent service name + shared /workspace
-AGENT_BASE_URL=http://platform-agent:8000
-SURFACES_WORKSPACE_DIR=/workspace
+# production handoff: bot connects to externally managed agent endpoint
+AGENT_BASE_URL=https://lambda.coredump.ru/agent_0/
+SURFACES_WORKSPACE_DIR=/agents
+SURFACES_SHARED_VOLUME=surfaces-agents
+
+# internal full-stack compose defaults
+AGENT_ID=matrix-dev
 
 # platform-agent provider
 PROVIDER_MODEL=openai/gpt-4o-mini
@@ -137,19 +141,28 @@ PROVIDER_API_KEY=...
 2. Если готовишься к multi-agent routing, добавь `MATRIX_AGENT_REGISTRY_PATH=config/matrix-agents.yaml` в `.env`
 3. Этот registry сейчас является конфигурационным артефактом Task 1; текущий Matrix runtime его ещё не читает
 
-### 4. Compose runtime
+### 4. Compose artifacts
 
-Root `docker-compose.yml` теперь является основным локальным runtime для Matrix и platform-agent.
-Он поднимает `matrix-bot`, `platform-agent` и общий volume `/workspace`.
+Production handoff uses `docker-compose.prod.yml`.
+Этот файл поднимает только `matrix-bot`, монтирует shared volume в `/agents` и ожидает, что `AGENT_BASE_URL`
+указывает на уже управляемый внешней платформой agent endpoint.
 
 ```bash
-docker compose up --build
+docker compose --env-file .env -f docker-compose.prod.yml up -d --build
 ```
 
-Compose собирает `platform-agent` из актуального upstream `external/platform-agent` Dockerfile (`development` target),
-монтирует live-код из `external/platform-agent/src` и `external/platform-agent_api`, и подготавливает shared `/workspace`
-с правами для agent runtime.
-Matrix бот подключается к `platform-agent` по service name, а не к отдельно запущенному `localhost`.
+Internal full-stack E2E uses `docker-compose.fullstack.yml`.
+Этот файл поднимает `matrix-bot` вместе с локальным `platform-agent`, использует тот же shared volume
+(`SURFACES_SHARED_VOLUME`) и ждёт `service_healthy` вместо sleep-based sequencing.
+
+```bash
+docker compose --env-file .env -f docker-compose.fullstack.yml up --build
+```
+
+`docker-compose.fullstack.yml` собирает `platform-agent` из актуального upstream `external/platform-agent`
+(`development` target), монтирует live-код из `external/platform-agent/src` и `external/platform-agent_api`,
+а shared volume виден как `/agents` в bot container и как `/workspace` в `platform-agent`.
+Старый root compose harness остаётся только как historical local reference и больше не является рекомендуемым runtime path.
 
 На `2026-04-21` локальный compose runtime использует vendored upstream-версии платформы без локальных патчей:
 
@@ -159,7 +172,7 @@ Matrix бот подключается к `platform-agent` по service name, а
 ### 4. Staged attachments в Matrix
 
 Если Matrix-клиент отправляет файлы отдельными media events, бот не вызывает агента сразу.
-Вместо этого он сохраняет файлы в shared `/workspace`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения.
+Вместо этого он сохраняет файлы в shared `/agents`, ставит их в очередь для конкретного чата и пользователя, и ждёт следующего обычного сообщения.
 
 Как отправить файлы агенту: