diff --git a/tools/local-dev/README.md b/tools/local-dev/README.md
index ee928bf..142b5bf 100644
--- a/tools/local-dev/README.md
+++ b/tools/local-dev/README.md
@@ -143,6 +143,28 @@ To point the proxy at a non-local gateway, run
 `VITE_DEV_PROXY_TARGET=http://gateway.host:8080 pnpm -C ui/frontend dev`
 — no compose changes needed.
 
+## Refreshing after Go-side changes
+
+`make up` reuses any pre-built images and, by default, only rebuilds
+the engine image (`build-engine`) when the tag is missing. Touching
+backend or gateway code (handlers, routes, transcoders, model
+constants) **does not** trigger a rebuild on its own — the next
+`docker compose up -d` will reattach to the stale image and the
+new behaviour silently disappears. After any change under
+`backend/`, `gateway/`, `pkg/`, or the FBS schemas, force a
+rebuild:
+
+```sh
+make -C tools/local-dev rebuild
+```
+
+`rebuild` runs `compose build --no-cache backend gateway` followed
+by `up -d --wait`, so the next request through the stack hits the
+new code. Engine code lives in a separate image — touch the engine
+and run `make stop-engines` plus `docker rmi galaxy-engine:local-dev`
+before `make up` (or `make build-engine`) so per-game containers
+respawn from the freshly built layers.
+
 ## Make targets
 
 ```text