docs(05-04): document split deployment artifacts

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

docs/deploy-architecture.md

@@ -4,6 +4,18 @@
 
 ---
 
+## Compose Artifacts
+
+- **Production deploy:** `docker-compose.prod.yml`
+  Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`, требует внешний `AGENT_BASE_URL`.
+- **Internal full-stack E2E:** `docker-compose.fullstack.yml`
+  Внутренний harness. Поднимает `matrix-bot` и `platform-agent`, использует тот же volume name и health-gated startup через `condition: service_healthy`.
+
+Production operators should run the bot with `docker-compose.prod.yml`; internal verification should use `docker-compose.fullstack.yml`.
+Старый root compose harness больше не является primary runtime contract для Phase 05.
+
+---
+
 ## Топология
 
 ```
@@ -22,7 +34,7 @@ lambda.coredump.ru
 
 - **Один инстанс Matrix-бота** обслуживает всех пользователей.
 - **Один агент-контейнер на пользователя.** Изоляция по agent_id, не через chat_id внутри одного инстанса.
-- **Shared volume** `/agents/` смонтирован и в Matrix-бот, и в каждый агент-контейнер. Агент видит свой подкаталог как `/workspace`.
+- **Shared volume** `/agents/` смонтирован в Matrix-бот. В internal full-stack harness тот же volume mounted as `/workspace` inside `platform-agent`, чтобы bot-side absolute paths и agent workspace относились к одному и тому же хранилищу.
 
 ---
 
@@ -58,24 +70,25 @@ agents:
 ```python
 from lambda_agent_api.agent_api import AgentApi
 
-connected_agents: dict[str, AgentApi] = {}
+connected_agents: dict[tuple[str, int], AgentApi] = {}
 
 def on_agent_disconnect(agent: AgentApi):
-    del connected_agents[agent.id]
+    connected_agents.pop((agent.id, agent.chat_id), None)
 
-async def on_message(matrix_user_id: str, text: str):
+async def on_message(matrix_user_id: str, matrix_room_id: str, text: str):
     agent_id = get_agent_id_by_user(matrix_user_id)  # из user_agents конфига
+    platform_chat_id = get_room_platform_chat_id(matrix_room_id)
 
-    agent = connected_agents.get(agent_id)
+    agent = connected_agents.get((agent_id, platform_chat_id))
     if not agent:
         agent = AgentApi(
             agent_id,
             get_agent_base_url(agent_id),        # ws://lambda.coredump.ru:7000/agent_0/
             on_disconnect=on_agent_disconnect,
-            chat_id=0,                            # default, один чат на агента
+            chat_id=platform_chat_id,            # отдельный thread на Matrix room
         )
         await agent.connect()
-        connected_agents[agent_id] = agent
+        connected_agents[(agent_id, platform_chat_id)] = agent
 
     async for event in agent.send_message(text):
         ...
@@ -86,7 +99,7 @@ async def on_message(matrix_user_id: str, text: str):
 AgentApi(
     agent_id: str,
     base_url: str,            # ws://host:port/agent_N/
-    chat_id: int = 0,         # default — один чат на агента
+    chat_id: int = 0,         # surfaces must supply per-room platform_chat_id
     on_disconnect: callable,
 )
 ```
@@ -111,7 +124,7 @@ AgentApi(
 2. Matrix-бот читает файл: `/agents/{N}/output/report.pdf`
 3. Отправляет как Matrix file message пользователю
 
-**Ключевое:** поверхность видит `/agents/` целиком через shared volume. Прямой HTTP-доступ к файлам не нужен.
+**Ключевое:** production handoff через `docker-compose.prod.yml` и internal E2E через `docker-compose.fullstack.yml` используют один и тот же `/agents` contract на стороне поверхности. Прямой HTTP-доступ к файлам не нужен.
 
 ---
 
@@ -140,6 +153,6 @@ AgentApi(
 ## Что НЕ решено / открытые вопросы
 
 - Ветка `platform-agent_api #9-clientside-tool-call` убирает `attachments` и `MsgEventSendFile` — пока игнорируем, используем master. Уточнить у Азамата сроки мержа перед деплоем.
-- `chat_id` — при нашей модели C1/C2/C3 каждый чат должен иметь отдельный `chat_id`. Нужно решить: один `AgentApi` на агента (chat_id=0) или по инстансу на чат (chat_id=1/2/3). Пока берём `chat_id=0` (один контекст на пользователя).
+- `chat_id` — каждый Matrix chat room должен иметь собственный `platform_chat_id`. `!clear` должен ротировать `platform_chat_id` только для текущей комнаты, чтобы получить новый thread и чистый контекст без смены Matrix room.
 - Composio `AGENT_ID` в `.env` для каждого агента — уточнить у платформы значения.
 - Что происходит с историей при рестарте агента — `MemorySaver` не персистентный.