docs: reorder & testing

integration/README.md

@@ -5,6 +5,13 @@ from outside and verifies behaviour at the public boundary while
 `backend` and `galaxy/game` run as Docker containers managed by the
 test process via `testcontainers-go`.
 
+For cross-cutting testing principles (unit vs integration boundaries,
+why testcontainers tests pin no-op observability providers, why
+infrastructure failures in this suite fail loudly instead of skipping)
+see [`docs/TESTING.md`](../docs/TESTING.md). This README focuses on
+the integration-specific runbook: prerequisites, entry points,
+labels, and per-test fixtures.
+
 ## Prerequisites
 
 - A reachable Docker daemon (`DOCKER_HOST` or the local socket).
@@ -15,10 +22,40 @@ test process via `testcontainers-go`.
 
 ## Run
 
+The recommended entry points are the Makefile targets:
+
 ```bash
-go test ./integration/...
+make -C integration preclean          # idempotent leftover cleanup
+make -C integration integration       # preclean + serial test run
+make -C integration integration-step  # preclean + one-test-at-a-time
 ```
 
+`preclean` removes stale containers and locally-built images from
+earlier runs; it never touches testcontainers-pulled service images
+(`postgres:16-alpine`, `axllent/mailpit`, `redis:7-alpine`,
+`testcontainers/ryuk`), so the cache stays warm. The cleanup keys
+off labels:
+
+- `org.testcontainers=true` — every container/network created by
+  `testcontainers-go` (our backend/gateway/game and the postgres /
+  redis / mailpit / ryuk service containers).
+- `galaxy.backend=1` — engine instances spawned by backend's runtime
+  adapter directly on the host Docker daemon (see
+  `backend/internal/dockerclient/types.go`).
+- `galaxy.test.kind=integration-image` — local builds of
+  `galaxy/{backend,gateway,game}:integration` produced by
+  `testenv/images.go`.
+
+`integration` runs every test in the module sequentially
+(`-p=1 -parallel=1`) — recommended default on a slow / shared Docker.
+`integration-step` runs them one at a time with a fresh preclean
+before each test and stops on the first failure; useful to isolate a
+flake or build up to a full pass without losing context to subsequent
+tests.
+
+Direct `go test ./integration/...` still works but does not pre-clean
+or serialise the suite; use it only on a hand-cleaned Docker.
+
 The suite builds three Docker images on demand from the workspace
 sources:
 
@@ -27,8 +64,10 @@ sources:
 - `galaxy/game:integration`     (`game/Dockerfile`).
 
 Each image is built once per `go test` invocation, guarded by a
-`sync.Once` inside `testenv`. The first cold run is slow (~2–3 min on
-a developer machine); subsequent runs reuse the layer cache.
+`sync.Once` inside `testenv`, and stamped with the
+`galaxy.test.kind=integration-image` label so `preclean` can wipe it
+on the next run. The first cold run is slow (~2–3 min on a
+developer machine); subsequent runs reuse the layer cache.
 
 ## Skipping