docs: document sibling-container networking gotcha

CLAUDE.md

@@ -311,7 +311,7 @@ The agent's first action on every fresh tenant is `do_first_hour_of_work`, a sin
 
 **Factory pattern for MCP servers:** The SDK connects each MCP server instance to one transport and rejects reuse. In-process MCP servers must be recreated per query() call. The registries they wrap are singletons, but the MCP server wrapper is new each time.
 
-**Docker socket mount (not DinD):** Agent creates sibling containers via the host Docker daemon. Docker-in-Docker requires --privileged mode. This matches CI systems (GitHub Actions, Jenkins). The socket is root-equivalent access, which is acceptable because the agent already has full shell access.
+**Docker socket mount (not DinD):** Agent creates sibling containers via the host Docker daemon. Docker-in-Docker requires --privileged mode. This matches CI systems (GitHub Actions, Jenkins). The socket is root-equivalent access, which is acceptable because the agent already has full shell access. Sibling containers default to the `bridge` network and are unreachable from phantom; attach with `--network phantom_phantom-net` at launch (or `docker network connect phantom_phantom-net <container>` after the fact) — see [docs/getting-started.md](docs/getting-started.md#networking-for-sibling-containers).
 
 **Tailwind v4 Browser CDN:** No build step for agent-generated pages. The agent creates HTML files in public/ and they render immediately. Theme variable declarations go in `<style type="text/tailwindcss">`, custom CSS referencing those variables goes in a plain `<style>` block.
 

docs/getting-started.md

@@ -288,6 +288,29 @@ echo "DOCKER_GID=YOUR_GID_HERE" >> .env
 docker compose down && docker compose up -d
 ```
 
+### Networking for sibling containers
+
+The Phantom stack runs on a private Docker bridge network named `phantom_phantom-net`. A sibling container created with a plain `docker run` lands on the default `bridge` network instead, and the two bridges have no route between them — phantom cannot reach the new container even though both use the same Docker daemon.
+
+To make a sibling container reachable, attach it to `phantom_phantom-net` at launch:
+
+```bash
+docker run -d --name pg-repro \
+  --network phantom_phantom-net \
+  -e POSTGRES_PASSWORD=postgres postgres:16
+
+# From inside phantom, the container is reachable by name:
+pg_isready -h pg-repro -p 5432
+```
+
+For an already-running container on the default bridge, connect it after the fact:
+
+```bash
+docker network connect phantom_phantom-net <container>
+```
+
+On `phantom_phantom-net`, container names resolve via Docker's embedded DNS, so addressing by `<container-name>:<port>` works without an IP lookup. If a sibling needs to bind a port for the host instead (e.g. for browser access from outside the VM), leave it on `bridge` and use `-p` port mapping; expect to lose reachability from phantom in that mode.
+
 ### Optional: HTTPS with a domain
 
 If you want Phantom accessible on a public domain (e.g., `phantom.yourdomain.com`):