diff --git a/docs/deployment.md b/docs/deployment.md
index a13e972..9805e0c 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -10,6 +10,21 @@ This document describes the GitOps-lite deployment process for the homelab.
 4.  **Tailscale Mesh**: All hosts are connected via Tailscale, allowing secure communication without public port exposure.
 5.  **Host Autonomy**: Services that must operate during WAN or Git outages keep their runtime dependencies on the execution node or local LAN.
 
+## ⚠️ ZNANY BUG — `deploy.sh vps` niszczy control-plane (2026-06-25)
+
+`deploy.sh vps` uruchamia `deploy-node.sh` w pętli po wszystkich serwisach VPS, w tym
+`control-plane`. Pętla używa innego `COMPOSE_PROJECT_NAME` niż `deploy-local.sh`
+(który uruchamiany jest z `cwd=services/control-plane`). Niezgodność project-name powoduje
+`Recreate` → `No such container` → `set -e` przerywa pętlę → **observer, supervisor,
+executor i operator-ui znikają z VPS.**
+
+**Dopóki bug nie zostanie naprawiony (backlog — Krytyczny):**
+- Do deployu control-plane używać: `ssh -t vps 'cd ~/homelab-codex-ws && cd services/control-plane && bash deploy-local.sh'`
+- Inne serwisy VPS deployować punktowo: `deploy-node.sh` z `--service <name>` lub przez SSH + `docker compose up -d`
+- **NIE uruchamiać `deploy.sh vps` bez pełnej świadomości ryzyka.**
+
+---
+
 ## Staged Deployment Framework
 
 The homelab uses a modularized staged deployment framework located at `scripts/deploy/deploy.sh`. This script is designed to be resumable, stage-aware, and observable, with core logic split into maintainable libraries in `scripts/lib/`.