From 28b12240014a0ae035257da03176239241a55810 Mon Sep 17 00:00:00 2001
From: oskar <oskar@kapalla.org>
Date: Tue, 4 Aug 2026 15:07:09 +0200
Subject: [PATCH] feat(kb): SPLIT deployment -> subsystem + incident
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

kb/subsystems/deployment.md — konwencje deployu
kb/incidents/deploy-sh-vps-niszczy-control-plane.md — sekcja
  "ZNANY BUG — deploy.sh vps niszczy control-plane (2026-06-25)"

UWAGA: "Recovery Workflow" to ### zagniezdzone w "Staged Deployment
Framework". Split mechaniczny tnie wylacznie po ##, a wyciagniecie tego
fragmentu wymagaloby przebudowy tresci — zostaje w dokumencie glownym.
Do rozwazenia jako osobny runbook w etapie redakcyjnym.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../deploy-sh-vps-niszczy-control-plane.md    | 27 +++++++++++++++++++
 {docs => kb/subsystems}/deployment.md         | 25 +++++++----------
 2 files changed, 37 insertions(+), 15 deletions(-)
 create mode 100644 kb/incidents/deploy-sh-vps-niszczy-control-plane.md
 rename {docs => kb/subsystems}/deployment.md (89%)

diff --git a/kb/incidents/deploy-sh-vps-niszczy-control-plane.md b/kb/incidents/deploy-sh-vps-niszczy-control-plane.md
new file mode 100644
index 0000000..f870e14
--- /dev/null
+++ b/kb/incidents/deploy-sh-vps-niszczy-control-plane.md
@@ -0,0 +1,27 @@
+---
+okf: "0.1"
+type: incident
+visibility: private
+status: active
+updated: 2026-06-25
+links:
+  - ../subsystems/deployment.md
+---
+
+# ZNANY BUG — `deploy.sh vps` niszczy control-plane (2026-06-25)
+
+## ⚠️ 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.**
+
+---
+
diff --git a/docs/deployment.md b/kb/subsystems/deployment.md
similarity index 89%
rename from docs/deployment.md
rename to kb/subsystems/deployment.md
index 9805e0c..ba036ae 100644
--- a/docs/deployment.md
+++ b/kb/subsystems/deployment.md
@@ -1,3 +1,13 @@
+---
+okf: "0.1"
+type: subsystem
+visibility: private
+status: active
+updated: 2026-06-25
+links:
+  - ../incidents/deploy-sh-vps-niszczy-control-plane.md
+---
+
 # Deployment Conventions
 
 This document describes the GitOps-lite deployment process for the homelab.
@@ -10,21 +20,6 @@ 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/`.