diff --git a/CLAUDE.md b/CLAUDE.md
index d16970e..5a2e658 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,3 +7,7 @@ Issues live as Gitea issues on `git.arthurerlich.de` (repo `haylan/LLM-Server`);
 ### Domain docs
 
 Single-context: `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+### Deploying changes
+
+The running stack lives on a separate box (the R9700 server), not wherever this repo is being edited. After **any** change to `docker-compose.yml`, `litellm-config.yaml`, `.env.example`, or a script under `scripts/`, commit/push it, then run `./scripts/update.sh` on the server to apply it — don't just describe the change as done. If this session doesn't have shell access to the server, say so explicitly and tell the user to run it themselves rather than leaving it unsaid.
diff --git a/README.md b/README.md
index 37805a5..ba2660b 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,8 @@ docker compose up -d
 
 Pointing Claude Code CLI, Kimi CLI, or OpenCode CLI at the local endpoint: see [`docs/coding-cli-setup.md`](docs/coding-cli-setup.md).
 
+**Applying updates**: after pulling changes (or editing `docker-compose.yml`/`litellm-config.yaml`/`.env` yourself), run `./scripts/update.sh` — pulls, validates the compose config, rebuilds/re-pulls images, and recreates whatever changed. Safe to run any time.
+
 **Known risk**: Qwen3.8-27B's tool-calling reliability against llama.cpp's Anthropic shim is not yet verified (open upstream parser bugs against its model lineage) — see `docs/research/qwen3.8-27b-tool-calling.md`.
 
 ## AI proxy (LiteLLM)
diff --git a/scripts/update.sh b/scripts/update.sh
new file mode 100644
index 0000000..4da1225
--- /dev/null
+++ b/scripts/update.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# The one command to run after any change to this repo (compose file,
+# litellm-config.yaml, .env, or a git pull) to bring the running stack in
+# sync. Pulls, validates, rebuilds/re-pulls images, and recreates only what
+# changed — safe to run any time, including with nothing to do.
+#
+# ponytail: no rollback/backup logic — this is a single-user homelab box,
+# not a fleet. If a bad config lands, `git revert` + re-run is the recovery
+# path, not this script.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+echo "==> git pull"
+git pull --ff-only
+
+echo "==> validating compose config"
+docker compose config -q
+
+echo "==> pulling images"
+docker compose pull --ignore-buildable
+
+echo "==> rebuilding local-build services (e.g. litellm-pgvector)"
+docker compose build --pull
+
+echo "==> recreating changed services"
+docker compose up -d --remove-orphans
+
+echo "==> status"
+docker compose ps