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

tests/test_deploy_handoff.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _compose(path: str) -> dict:
+    return yaml.safe_load((ROOT / path).read_text(encoding="utf-8"))
+
+
+def test_prod_compose_uses_registry_image_not_local_build():
+    prod = _compose("docker-compose.prod.yml")
+    service = prod["services"]["matrix-bot"]
+
+    assert "image" in service
+    assert "build" not in service
+    assert service["image"].startswith("${SURFACES_BOT_IMAGE:?")
+
+
+def test_fullstack_compose_keeps_local_dev_build_with_agent_api_context():
+    fullstack = _compose("docker-compose.fullstack.yml")
+    service = fullstack["services"]["matrix-bot"]
+
+    assert service["build"]["target"] == "development"
+    assert service["build"]["additional_contexts"]["agent_api"] == "./external/platform-agent_api"
+    assert service["extends"]["file"] == "docker-compose.prod.yml"
+
+
+def test_dockerfile_production_build_does_not_require_local_external_tree():
+    dockerfile = (ROOT / "Dockerfile").read_text(encoding="utf-8")
+
+    assert "/app/external/platform-agent_api" not in dockerfile
+    assert "external/platform-agent_api" not in dockerfile
+    assert "git+https://git.lambda.coredump.ru/platform/agent_api.git" in dockerfile
+    assert "python -m pip install --no-cache-dir --ignore-requires-python" in dockerfile
+    assert "uv pip install --system --ignore-requires-python" not in dockerfile
+
+
+def test_dockerignore_excludes_local_only_and_runtime_artifacts():
+    dockerignore = (ROOT / ".dockerignore").read_text(encoding="utf-8")
+
+    assert "external/" in dockerignore
+    assert ".planning/" in dockerignore
+    assert "config/matrix-agents.yaml" in dockerignore
+    assert ".env" in dockerignore
+
+
+def test_agent_registry_example_documents_multi_agent_volume_contract():
+    registry = yaml.safe_load(
+        (ROOT / "config" / "matrix-agents.example.yaml").read_text(encoding="utf-8")
+    )
+    agents = registry["agents"]
+
+    assert len(agents) >= 3
+    assert len({agent["id"] for agent in agents}) == len(agents)
+    assert len({agent["workspace_path"] for agent in agents}) == len(agents)
+    for index, agent in enumerate(agents):
+        assert agent["base_url"].endswith(f"/agent_{index}/")
+        assert agent["workspace_path"] == f"/agents/{index}"