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

README.md

@@ -4,7 +4,7 @@ Matrix-бот для взаимодействия пользователя с AI
 
 ## Интеграция для платформы
 
-Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами.
+Бот — это один Docker-контейнер (`matrix-bot`), который вы добавляете в свою инфраструктуру рядом с агентами. Production target — один surface container на 25-30 внешних agent containers/services.
 
 ### Что бот ожидает от вас
 
@@ -37,10 +37,11 @@ Bot container                  Agent containers
 
 ### Минимальный чеклист
 
+- [ ] Взять опубликованный image `SURFACES_BOT_IMAGE` или собрать production image из этого репозитория
 - [ ] Заполнить `config/matrix-agents.yaml` — ID агентов, `base_url` каждого, `workspace_path`, маппинг пользователей
 - [ ] Задать переменные окружения (см. `.env.example`): Matrix credentials, `MATRIX_PLATFORM_BACKEND=real`, `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`
 - [ ] Смонтировать в бот-контейнер shared volume как `/agents` — каждый агент должен видеть свою поддиректорию как `/workspace`
-- [ ] Добавить бот-сервис в свой compose (используйте `docker-compose.prod.yml` как шаблон сервиса)
+- [ ] Добавить bot-only service в свой compose; агенты в этот compose не входят и управляются платформой
 
 ---
 
@@ -94,6 +95,7 @@ cp .env.example .env
 | `MATRIX_USER_ID` | ✓ | `@bot:example.org` |
 | `MATRIX_PASSWORD` | ✓ | пароль (или `MATRIX_ACCESS_TOKEN`) |
 | `MATRIX_PLATFORM_BACKEND` | ✓ | `real` для продакшна |
+| `SURFACES_BOT_IMAGE` | ✓ | Docker image поверхности: `mput1/surfaces-bot:latest` |
 | `AGENT_BASE_URL` | | Fallback URL агента если `base_url` не задан в `matrix-agents.yaml` |
 | `MATRIX_AGENT_REGISTRY_PATH` | ✓ | путь к реестру внутри контейнера: `/app/config/matrix-agents.yaml` |
 | `SURFACES_WORKSPACE_DIR` | | путь к shared volume в контейнере (по умолчанию `/agents`) |
@@ -117,31 +119,57 @@ 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. Если пользователь не найден — используется первый агент.
 - `base_url` — HTTP URL агент-эндпоинта (path-based routing через reverse proxy).
 - `workspace_path` — путь к воркспейсу агента внутри бот-контейнера на shared volume.
   Бот сохраняет входящие файлы в `{workspace_path}/incoming/`, агент пишет исходящие в свой `/workspace/`.
+- Для 25-30 агентов продолжайте тот же паттерн: `/agent_17/` + `/agents/17`, `/agent_29/` + `/agents/29`.
 
 Полный пример с комментариями: `config/matrix-agents.example.yaml`
 
 ### Production (bot-only)
 
-`docker-compose.prod.yml` — шаблон сервиса `matrix-bot`. Платформа добавляет этот сервис в свой compose рядом с агент-контейнерами, монтирует shared volume и задаёт переменные окружения.
+`docker-compose.prod.yml` — bot-only handoff через published image. Платформа добавляет этот сервис в свой compose рядом с agent containers, монтирует shared volume и задаёт переменные окружения. Этот compose не создаёт и не собирает агент-контейнеры.
 
-Для изолированного запуска бота без агентов (smoke-тест):
+Для запуска опубликованного image:
 ```bash
-docker compose --env-file .env -f docker-compose.prod.yml up -d --build
+export SURFACES_BOT_IMAGE=mput1/surfaces-bot:latest
+docker compose --env-file .env -f docker-compose.prod.yml up -d
 ```
 
+Опубликованный image:
+
+```text
+mput1/surfaces-bot:latest
+sha256:26ba3a49290ab7c1cf0fa97f3de3fefdc70b59df7e6f1e0c2255728f8e2369be
+```
+
+Для сборки и публикации surface image:
+```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"
+```
+
+Если push возвращает `insufficient_scope`, текущий Docker login не имеет доступа к namespace/repository. Создайте repository в нужном Docker Hub namespace или перетегируйте image в namespace пользователя, под которым выполнен `docker login`.
+
 ### Fullstack E2E (bot + agent)
 
 ```bash
 docker compose --env-file .env -f docker-compose.fullstack.yml up --build
 ```
 
-Поднимает `matrix-bot` вместе с локальным `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте.
+Поднимает `matrix-bot` вместе с локальным `platform-agent`. Это internal harness, не production topology на 25-30 агентов. `matrix-bot` собирается через Dockerfile target `development` и локальный `external/platform-agent_api` context, как в dev-сборке `platform-agent`. `AGENT_BASE_URL` перекрывается на `http://platform-agent:8000`. Shared volume виден как `/agents` в боте и `/workspace` в агенте.
 
 ### Сброс состояния (локально)
 
@@ -159,8 +187,8 @@ Bot (/agents)              Agent (/workspace = /agents/N/)
   /agents/0/output/    ←────────────────────────────────→  /workspace/output/
 ```
 
-- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, передаёт агенту `attachments=["incoming/{stamp}-{file}"]`
-- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file` и отправляет пользователю как Matrix file message
+- **Входящий файл** (пользователь → агент): бот сохраняет в `{workspace_path}/incoming/{stamp}-{file}`, например `/agents/17/incoming/report.pdf`, и передаёт агенту `attachments=["incoming/{stamp}-{file}"]`
+- **Исходящий файл** (агент → пользователь): агент пишет в `/workspace/output/file`, бот читает из `{workspace_path}/output/file`, например `/agents/17/output/file`, и отправляет пользователю как Matrix file message
 - `workspace_path` для каждого агента задаётся в `config/matrix-agents.yaml`
 
 ---