docs(deploy): finalize multi-agent surface image handoff

docs/deploy-architecture.md

@@ -7,10 +7,10 @@
 ## Compose Artifacts
 
 - **Production deploy:** `docker-compose.prod.yml`
-  Bot-only handoff. Поднимает только `matrix-bot`, монтирует shared volume в `/agents`.
-  Платформа предоставляет агент-контейнеры отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`.
+  Bot-only handoff через published image (`SURFACES_BOT_IMAGE`). Поднимает только `matrix-bot`, монтирует shared volume в `/agents`.
+  Платформа предоставляет 25-30 agent containers/services отдельно; бот подключается к ним через `base_url` из `matrix-agents.yaml`.
 - **Internal full-stack E2E:** `docker-compose.fullstack.yml`
-  Внутренний harness для тестирования. Поднимает `matrix-bot` и один `platform-agent`, health-gated startup.
+  Внутренний harness для тестирования. Локально собирает `matrix-bot` через Dockerfile target `development`, поднимает один `platform-agent`, health-gated startup.
 
 Production operators: `docker-compose.prod.yml`. Internal E2E: `docker-compose.fullstack.yml`.
 
@@ -33,7 +33,7 @@ lambda.coredump.ru
 ```
 
 - **Один инстанс Matrix-бота** обслуживает всех пользователей.
-- **Один агент-контейнер на пользователя.** Изоляция по agent_id, не через chat_id внутри одного инстанса.
+- **Один агент-контейнер на пользователя.** Production scale target: 25-30 внешних агентов. Изоляция по `agent_id`, не через один общий agent instance.
 - **Shared volume** `/agents/` смонтирован в Matrix-бот. В internal full-stack harness тот же volume mounted as `/workspace` inside `platform-agent`, чтобы bot-side absolute paths и agent workspace относились к одному и тому же хранилищу.
 
 ---
@@ -58,12 +58,49 @@ agents:
     label: "Agent 1"
     base_url: "http://lambda.coredump.ru:7000/agent_1/"
     workspace_path: "/agents/1"
+
+  - id: agent-2
+    label: "Agent 2"
+    base_url: "http://lambda.coredump.ru:7000/agent_2/"
+    workspace_path: "/agents/2"
 ```
 
 - `user_agents` — маппинг Matrix user_id → agent_id. Если пользователь не найден — используется первый агент из списка.
 - `agents[].base_url` — HTTP URL агент-эндпоинта. Бот подключается через AgentApi.
 - `agents[].workspace_path` — абсолютный путь к воркспейсу агента **внутри контейнера бота** (т.е. на shared volume).
   Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, читает исходящие из `{workspace_path}/`.
+- Для 25-30 агентов продолжайте тот же паттерн до нужного номера: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`.
+
+## Surface Image Build Contract
+
+Production image содержит только Matrix surface. Он не содержит `platform-agent` и не требует локального `external/` build context.
+
+```bash
+docker login
+export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+
+docker build --target production \
+  --build-arg LAMBDA_AGENT_API_REF=master \
+  -t "$SURFACES_BOT_IMAGE" .
+docker push "$SURFACES_BOT_IMAGE"
+```
+
+Published image:
+
+```text
+mput1/surfaces-bot:latest
+sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be
+```
+
+`SURFACES_BOT_IMAGE` должен указывать на registry namespace, куда текущий Docker account может пушить. Ошибка `insufficient_scope` означает, что пользователь не залогинен в этот namespace, repository не создан, или у аккаунта нет push-доступа.
+
+Production Dockerfile ставит `platform/agent_api` из Git по тому же принципу, что и `platform-agent` production image:
+
+```bash
+git+https://git.lambda.coredump.ru/platform/agent_api.git
+```
+
+Локальный `docker-compose.fullstack.yml` остаётся dev/E2E harness: он использует target `development` и `additional_contexts.agent_api=./external/platform-agent_api`, чтобы можно было тестировать surface вместе с локальным checkout SDK.
 
 ---